DAGrunner documentation
Sphinx syntax and subsequently building documentation can be fraught with frustration and burden. It is for this reason that it was decided to experiment with an alternative approach, which is to take advantage of native github markdown rendering support.
A script has been written to generate markdown reference documentation from a python package. This python script is available at docs/gen_docs. This is a WIP and will likely improve over time. It may also become pulled out into its own repository if deemed useful elsewhere. For DAGrunner, writing to the current working directory (docs), this would be done as follows:
gen_docs dagrunner .
This will generate files for your package with the following naming <package>.<subpackage>.<module>.md
Additionally an index file is generated <package>_index.md
For DAGrunner, see here
From the README.md, we can access the reference documentation by following the link:
Here is a preview of the index that the above link takes us to, giving us an overview of package:
Taking a look at one of the modules (dagrunner.execute_graph):
Syntax of the dagrunner.execute_graph.plugin_executor docstring (see here):
Note that any github flavoured markdown syntax is supported and module/function/class/method docstrings are parsed and included in the resulting reference documentation files.