Documentation tools: Sphinx, ...
Autodoc
- Jeroen worked on autodoc and partially "unforked" it. The Sage-specific fixes were kept, but sage_autodoc is now much closer to upstream than before. See http://trac.sagemath.org/ticket/20359
Upgrading to Sphinx 1.4
Robert worked on generating Sage docs with native Sphinx.
This should bring:
- native support parallelism
- removal of some hacks for Cython support
- ...
Sphinx 1.4 now mostly works, but the merging of the final index breaks badly: http://trac.sagemath.org/ticket/18497
Getting rid of autogenerated .rst stub files
Goals:
- simpler build system (no need to maintain essentially duplicate information)
- more robust build w.r.t. deleting python files
- cleaner, ...
Robert started implementing the required features in Sphinx master
Multidoc
TODO: Florent: status report
- Since 1.3, Sphinx can also read in parallel.
- [robert] sphinx-build -j ${NUMBER_OF_SAGE_DOC_PACKAGES} should ideally have the same effect.
- Original PR: https://bitbucket.org/birkenfeld/sphinx/pull-requests/108/wip-parallel-build-experimentation/diff
Analyzis of the memory footprint of Sphinx (Florent, Robert, Julien)
Analysis:
- A large cache is kept in memory for autofunction and automethods. Since we only use automodule, it could be dropped once the docstring of the module is analysed (TODO Upstream).
- The cache is filled with all docstring encoded in UCS32. Some string are 3BM large.
- Unpickling the environment and doctrees files takes anound 1.6GB that's what we might hope as a measure of peak memory consumption.
- The parallel compiling doesn't seem to increase significantly the needed memory.
Jupyter notebook exporter for Sphinx
Robert pointed to preliminary work by Harald Schilly: https://github.com/sphinx-doc/sphinx/pull/2117
To be discussed with Robert:
- Error reporting of Sphinx when documenting API. How to locate the error.?
Random notes
- Discussion on "inspect" I do not get because I do not know what "inspect" is
- This is time consuming: each time one has to rebuild the whole documentation.
- Jeroen is concerned about images in the docs and build times.