gavo.user.docgen module

Generation of system docs by introspection and combination with static docs.

class gavo.user.docgen.DocumentStructure

Bases: dict

a dict keeping track of what elements have been processed and which children they had.

From this information, it can later fill out the ParentPlaceholders left in the proto reference doc.

This also keeps track of what macros can be used where.

fillOut(protoDoc)

class gavo.user.docgen.KnownMacros

Bases: object

An accumulator for all macros known to the various DaCHS objects.

Note that macros with identical names are supposed to do essentially the same things. In particular, they must all have the same signature or the documentation will be wrong.

When macros share names, all but one implementation should have a docstring just saying “see <whatever>”; that way, the docstring actually chosen is deterministic.

addMacro(name, macFunc, foundIn)

registers macFunc as expanding name in the element foundIn.

macFunc is the method, foundIn is the python class it’s defined on.

getDocs()

returns RST lines describing all macros fed in in addMacro.

class gavo.user.docgen.MacroDoc(name, macFunc, foundIn)

Bases: object

documentation for a macro, including the objects that know about it.

addObject(macFunc, obj)

declares that macFunc is also available on the python object obj.

If also checks implements the “see <whatever>” mechanism described in KnownMacros.

makeDoc(content)

adds documentation of macFunc to the RSTFragment content.

class gavo.user.docgen.ParentPlaceholder(elementName)

Bases: object

is a sentinel left in the proto documentation, to be replaced by docs on the element parents found while processing.

class gavo.user.docgen.RSTFragment

Bases: object

is a collection of convenience methods for generation of RST.

addDLItem(term, definition)

addDefinition(defHead, defBody)

adds a definition list-style item .

defBody is re-indented with two spaces, defHead is assumed to only contain a single line.

addHead(head, underliner)

addHead1(head)

addHead2(head)

addNormalizedPara(stuff)

adds stuff to the document, making sure it’s not glued to any previous material and removing whitespace as necessary for docstrings.

addRaw(stuff)

addULItem(content, bullet='*')

delEmptySection()

deletes something that looks like a headline if it’s the last thing in our content list.

level1Underliner = "'"

level2Underliner = '.'

makeSpace()

adds an empty line unless the last line already is empty.

class gavo.user.docgen.StructDocMaker(docStructure)

Bases: object

A class encapsulating generation of documentation from structs.

addDocsFrom(klass, docStructure)

getDocs()

gavo.user.docgen.formatKnownMacros(docStructure)

gavo.user.docgen.getAPIDocs(docStructure)

gavo.user.docgen.getActiveTagDocs(docStructure)

gavo.user.docgen.getCoreDocs(docStructure)

gavo.user.docgen.getDocName(klass)

gavo.user.docgen.getGrammarDocs(docStructure)

gavo.user.docgen.getMetaKeyDocs()

gavo.user.docgen.getMixinDocs(docStructure, mixinIds)

gavo.user.docgen.getRegtestAssertions(docStructure)

gavo.user.docgen.getRendererDocs(docStructure)

gavo.user.docgen.getRmkFuncs(docStructure)

gavo.user.docgen.getStreamsDoc(idList)

gavo.user.docgen.getStructDocs(docStructure)

gavo.user.docgen.getStructDocsFromRegistry(registry, docStructure)

gavo.user.docgen.getTriggerDocs(docStructure)

gavo.user.docgen.html(args)

gavo.user.docgen.latex(args)

gavo.user.docgen.main()

gavo.user.docgen.makeReferenceDocs()

returns a restructured text containing the reference documentation built from the template in refdoc.rstx.

WARNING: refdoc.rstx can execute arbitrary code right now. We probably want to change this to having macros here.

gavo.user.docgen.makeSystemTablesList(docStructure)

gavo.user.docgen.refdoc(args)