WIP: Documentation generator from component code
This is a very early / not well integrated documentation generator for portal_components . It produces a zip file with html code.
I did not try all from https://wiki.python.org/moin/DocumentationTools but only:
- pydoc ( which I don't like )
- epydoc ( which I don't like so much )
- sphinx ( which I feel is acceptable )
- pdoc ( which I feel is acceptable )
if we ever integrate this further, we should probably choose one and stick to it. Sphinx is hard to integrate, this code generates some a folder with some rst files and run a full build. If we want to integrate a doc generation tool so that a request on a URL returns the doc for the module, pdoc might be easier, because it's API is really "generate doc for this module" ( this code hacks to generate docs for multiple modules at once )
the module names must match the key in sys.modules, ie. include the version (like erp5_version ).
-
marked as a Work In Progress
Toggle commit list -
This is not really for being merged as is, but share the code if it can help as a starting point for something better.
On the other hand, if someone need to generate code docs from components code, this seem to work already. The reason for doing this was that I need to answer "what's covered by the test suite?" to a project manager and I felt it this would be better to give something a bit more "higher level" that the source code.
example of generated files:
-
unmarked as a Work In Progress
Toggle commit list -
marked as a Work In Progress
Toggle commit list -
100 if backend == 'sphinx': 101 tmpdir = tempfile.mkdtemp() 102 try: 103 with open(os.path.join(tmpdir, 'conf.py'), 'w') as conf: 104 conf.write(""" 105 project = u'ERP5 Generated Documentation' 106 html_theme = 'default' 107 master_doc = 'index' 108 extensions = [ 109 'sphinx.ext.autodoc', 110 'sphinx.ext.autosummary', 111 'sphinx.ext.doctest', 112 'sphinx.ext.viewcode', 113 'sphinxcontrib.plantuml'] 114 115 plantuml = '/srv/slapgrid/slappart8/bin/plantuml' -
for reference, this is:
#!/bin/sh -e exec /srv/slapgrid/slappart8/srv/runner/software/c5be5b0096cd286c70df5156590cf4f6/parts/java-re-8/bin/java -jar /srv/slapgrid/slappart8/plantuml.jar "$@"I suggested a feature request to use URL here https://github.com/sphinx-contrib/plantuml/issues/21
see related MR to see an example of docstring format to use.
-
-
Please register or sign in to post a comment