Peeves.Doc
A simple documentation framework, similar to Sphinx.
It builds off of a template engine (provided by the TemplateEngine package) and an object-tree traversal
class (TemplateWalker) to fill out templates for the different types of python objects.
These templates are exported as Markdown so that they can be turned into a final website by a more sophisticated
Markdown -> HTML static site generator, like Jekyll.
Templates are extremely customizable (down to the object-level) with a flexible and powerful template mini-language
that builds off of python’s built-in AST module and syntax.
Examples are also possible to provide for individual objects/modules and can also be harvested automatically from
unit tests if provided.
Members
The templates provided are for modules, classes, methods, functions, and generic objects.
The mini-language used extends standard python string formatting syntax but allows for the
evaluation of a whitelisted set of commands within templates.
A full HTML/Bootstrap generator is included to allow for total customization of the generated
Markdown.
See TemplateOps, TemplateFormatDirective, MarkdownOps, and MarkdownFormatDirective for more info.
Examples
Before we can run our examples we should get a bit of setup out of the way. Since these examples were harvested from the unit tests not all pieces will be necessary for all situations.
All tests are wrapped in a test class
class DocsTests(TestCase):
"""
Sample documentation generator tests
"""
PeevesDoc
def test_PeevesDoc(self):
"""
Builds sample documentation for the Peeves package
:return:
:rtype:
"""
import os, tempfile
root = os.path.dirname(os.path.dirname(os.path.dirname(__file__)))
# with tempfile.TemporaryDirectory() as td:
td = '/var/folders/9t/tqc70b7d61v753jkdbjkvd640000gp/T/tmpo3b4ztrq/'
target = os.path.join(td, "docs")
doc_config = {
"config": {
"title": "Peeves",
"path": "Peeves",
"url": "https://mccoygroup.github.io/Peeves/",
"gh_username": "McCoyGroup",
"gh_repo": "Peeves",
"gh_branch": "master",
"footer": "Brought to you by the McCoy Group"
},
"packages": [
{
"id": "Peeves"
}
],
"root": root,
"target": target,
"readme": os.path.join(root, "blurb.md"),
'examples_directory': os.path.join(root, "ci", "examples"),
'tests_directory': os.path.join(root, "ci", "tests"),
'templates_directory': os.path.join(root, "ci", "templates")
}
DocBuilder(**doc_config).build()
ParseExamples
def test_ParseExamples(self):
parser = ExamplesParser.from_file(os.path.abspath(__file__))
self.assertTrue(hasattr(parser.functions, 'items'))
tests = TestExamplesFormatter.from_file(os.path.abspath(__file__))
print(tests.format())
FormatSpec
def test_FormatSpec(self):
fmt = inspect.cleandoc("""
### My Data
{$:b=loop(add_temp, l1, l2, slots=['l1', 'l2'])}
{$:len(b) ** 2}
""")
print("",
TemplateFormatter().format(fmt, param=2, l1=[1, 2, 3], l2=[4, 5, 6], add_temp='{l1} + {l2}', p1=1, p2=0),
sep="\n"
)