The documentation generally consists of two parts, the manual and API documentation.
The manual is an 100% handwritten collection of text files using restructured text markup which are bound together via index files. Index files are special in that they contain toctree directives to maintain a table of contents.
The API documentation is created automatically from the restructured text compatible doc strings of packages, modules, classes, methods and functions.
The layout and conversion of the markup is performed by sphinx. As the way sphinx generates the API documentation involves everything imported into the respective module, not only the defined routines are auto-documented, but also everything else. As this is hard to read and hard to understand at the current time, epydoc fills the gap and is provided as alternative API documentation.
In order to provide more information to the interested reader about the state of the project, a coverage report can be generated automatically and then linked to by the manual where needed.
The previously mentioned features involve multiple tools and passes to compile the final html documentation ( which is currently the only one being directly supported ).
The makedoc script is located in the doc directory and needs to be run from there or the doc directory of your derived project.
The script supports multiple flags to control the usage of individual features. To assure consistency, it will use the info module to retrieve basic project information.
If 1, default 1, a nose coverage report is created to which sphinx documents may link as required.
If set, instead of generating documentation, previously generated files will be removed. This flag modified all previously mentioned flags, and to clean only the coverage report, your would type:
$ ./makedoc --clean -e 0 -s 0 -c 1
Note
In order to generate sphinx or epydoc docuementation, sphinx and epydoc need to be installed in the python installation executing makedoc. To generate a coverage report, you will need nose and coverage installed in the interpreter matching your latest available maya version.
As building documentation can take a long time, especially if the sphinx API documentation is involved, it is useful to protect it from being regenerated unnecessarily, especially when setting up your project for distribution.
Assuming that it is usually enough to build the documentation once per project version, it only needs to be rebuild if your project version changed relative to the project version stored in the *.version_info files. One is created for each documentation target, so you will see epydoc.version_info, coverage.version_info and sphinx.version_info in your doc directory after a complete build.
Running makedoc will always regenerate the documentation, but when the script is executed from within the setup script, documentation generation will be skipped if the version_info matches the version you are currently distributing.
Note
This distribution behavior might not always be desired or correct - in the latter case it is up to your judgement to run a makedoc --clean before redoing the distribution.