pdk.Tools.pdkdoc_overview | index pdk/Tools/pdkdoc_overview.py |
use "structured text" to mark up Python doc strings. Advantages are: use pydoc to generate HTML pages from the sources. Features of pydoc are: Note that pydoc works by inspecting "live" objects, i.e., all modules that
are documented have to be imported in order to be documented. In rare cases
this might pose problems with circular imports which are easily resolved by
moving the offending import statements into the local namespace where they
are actually used. The following features were added to the standard version of pydoc to
accommodate the needs for the pdk code base: Please study the examples in this module and the links above to learn how to
structure and format Python object doc strings for pdk code. If you want to check how the formatted documentation for a module you wrote
looks like, you can do the following from the Python prompt: A typical interactive session looks like this: While this does not give you any hint where the error occurred, you will see
a nice HTML-formatted error message in the appropriate place in the generated
output. if a module to be documented defines an __all__ attribute, documentation
will be restricted to the identifiers listed therein. Note that any
references to identifiers not exported by __all__ will not be resolved,
even if they are imported into the module name space in order to process a single file from the command line, the file name needs
to contain at least one path separator; therefore, you need to do a in the current directory.pdk Python code documentation mini-HOWTO
Motivation
Approach
Implementation
Practical Use
from pdkdoc import writedoc
writedoc("packagepath.modulename")
>>> from pdkdoc import writedoc
>>> writedoc("pdk.DataBaseClasses")
writing documentation for pdk.DataBaseClasses...
Reporter: ERROR/3 (string input) Unexpected indentation at line 3.
Reporter: WARNING/2 (string input) Block quote ends without a blank line; unexpected unindent at line 4.
Reporter: WARNING/2 (string input) Enumerated list ends without a blank line; unexpected unindent at line 12.
...wrote pdk.DataBaseClasses.html
>>>
Random notes:
python pdkdoc.py -w ./myfile.py`` to process a file
Classes | ||||||||||||||||||||||||||
|
Functions | ||||||
|
Data | ||
__looksLikeABuiltinItem__ = 3 aString = 'this will pop up in the data section' singleton = instance of ProperlyDocumentedClass |