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 )
example usage: https://your.erp5.instance/erp5/ERP5Site_generateCodeDocumentation?backend=sphinx&module_name_list:list=erp5.component.test.erp5_version.testSupportRequest&module_name_list:list=erp5.component.test.erp5_version.testERP5Administration
the module names must match the key in
sys.modules, ie. include the version (like
This merge request is currently a Work In Progress
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 ProgressToggle commit list
bt5/erp5_code_documentation_generator/ExtensionTemplateItem/portal_components/extension.erp5.CodeDocumentationGenerator.py 0 → 100644
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.