doctools: Tools to parse and generate documentation¶

Tools to parse and generate documentation

This framework was particularly conceived to document cython projects which are badly supported with sphinx, but can be used to document pure python projects just as well.

The main backend is mkdocs and at the moment the documentation format supported is markdown, using docstring in google style

def func(a: type, b: type) -> rettype:
    '''
    Short description of func

    Longer description spanning
    multiple lines - Admonitions are allowed if
    enabled in mkdocs :

    !!! note

        My note admonition

    Args:
        * a: …
        * b: …

    Returns:
        My return value
    '''

One of the main advantages of this framework is that the documentation does not need to be built by the host (readthedocs, for example). Used together with mkdocs the documentation (markdown) is built locally and It can be built locally and checked into the git repo

Projects using this framework for documentation:

bpf4: https://github.com/gesellkammer/bpf4 (build script: https://github.com/gesellkammer/bpf4/blob/master/docs/generatedocs.py)
rtmidi2: https://github.com/gesellkammer/rtmidi2 (build script: https://github.com/gesellkammer/rtmidi2/blob/master/docs/generatedocs.py)
loristrck: https://github.com/gesellkammer/loristrck/blob/master/docs/generatedocs.py

A possible build script for a project’s documentation:

# generatedocs.py
import mymodule  # the module we want to document
from emlib import doctools
import os
from pathlib import Path

docsfolder = Path("docs")
renderConfig = doctools.RenderConfig(splitName=True, fmt="markdown", docfmt="markdown")
reference = doctools.generateDocsForModule(mymodule,
                                           renderConfig=renderConfig,
                                           exclude={'foo'},
                                           title="Reference")
os.makedirs(docsfolder, exist_ok=True)
open(docsfolder / "reference.md", "w").write(reference)
index = doctools.generateMkdocsIndex(projectName="mymodule",
                                     shortDescription="mymodule does something useful")
open(docsfolder / "index.md", "w").write(index)
root = docsfolder.parent
if (root/"mkdocs.yml").exists():
    os.chdir(root)
    os.system("mkdocs build")

Functions¶

`cache`(user_function, /)	Simple lightweight unbounded cache.
`externalModuleMembers`(module[, include_private])	Returns a list of member names which appear in dir(module) but are not defined there
`formatSignature`(name, signature[, maxwidth, ...])	Format a signature to align args
`fullname`(obj[, includeModule])	Given an object, returns its qualified name
`generateDocsForClass`(cls, renderConfig[, ...])	Generate documentation for the given class
`generateDocsForFunctions`(funcs[, ...])	Collects documentation for multiple functions in one string
`generateDocsForModule`(module[, ...])	Generate documentation for the given module
`generateMkdocsIndex`(projectName, ...[, ...])	Generate the template for an index file suitable for mkdocs
`generateModuleTOC`(members)	rtype: `str`
`getClassMembers`(cls[, exclude, inherited])	Inspects cls and determines its methods and properties
`getEmbeddedSignature`(objname, doc)	Returns the docstring embedded signature
`getModuleMembers`(module[, exclude, classesFirst])	Returns a dictionary of {membername:member} in order of appearence
`groupMembers`(members)	Sorts the members into three groups: functions, classes and modules
`hasEmbeddedSignature`(objname, doc)	Returns True if the docstring has an embedded signature
`isExtensionClass`(cls)	Returns True if cls is an extension class
`isMethodInherited`(cls, method)	Is this method inherited?
`markdownEscape`(s)	Escape s as markdown
`markdownHeader`(text, headernum[, inline])	Create a markdown header
`markdownReplaceHeadings`(s[, indentLevel, ...])	Replaces any heading of the form.
`parseClassDocstring`(cls)	Extract the docs of a class to a ParsedDef
`parseDef`(obj)	Parses a function/method, analyzing the signature / docstring.
`parseDocstring`(docstr[, fmt])	Parses a docstring, returns a ParsedDef
`renderClassDocstring`(cls, renderConfig[, ...])	Render the documentation for a given class
`renderDocumentation`(parsed, renderConfig, ...)	Renders the parsed function / method / property as documentation in the given format
`sortClassesByTree`(classes)	Sort classes according to their inheritance tree

Classes¶

`ClassMembers`(properties, methods)	Gathers members defined in a class
`ObjectKind`(value)	An enumeration.
`Param`(name[, type, descr, default, hasDefault])	Represents a parameter in a function/method
`ParseError`
`ParsedDef`([name, kind, params, returns, ...])	A ParsedDef is the result of parsing a function/method definition
`RenderConfig`([maxwidth, fmt, docfmt, ...])	A RenderConfig determines how the documentation is rendered