PyHelp-An Automatic Multi-Output Documentation Generator for Python

摘要

The DRACO code creates geometry and meshes through a command-line Python interface consisting of hundreds of classes and modules which must be accompanied by current documentation. The standard Python utility pydoc performs introspection on objects and prints their associated documentation strings verbatim. However, pydoc supports only very rudimentary formatting and cannot producand use the Doxygen tool to generate the needed forms of documentation. Codes with complex interfaces often require substantial effort to keep user documentation current with interface changes. The DRACO code creates geometry and meshes through a command-line Python interface consisting of hundreds of classes and thousands of functions. A previous attempt to write documentation manually quickly fell out of date, so the development team needed to find an alternative. The existing tools did not provide the flexibility we needed, and the team was already conversant in Doxygen, a C++ code-documenting utility with a simple tag-based markup. Python comes with a utility, pydoc, that performs introspection on objects and prints their docstrings verbatim. However, pydoc supports only very rudimentary formatting and cannot produce printable documentation. Thus we decided to create 'docstrings' written in Doxygen syntax for each object and process them with a modified pydoc to generate the needed forms of documentation.