|
⇤ ← Revision 1 as of 2017-01-09 21:48:16
Size: 2227
Comment:
|
Size: 2280
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| # Documentation tools: Sphinx, ... | = Documentation tools: Sphinx, ... = |
| Line 3: | Line 3: |
| ## Autodoc | == Autodoc == |
| Line 7: | Line 7: |
| ## Upgrading to Sphinx 1.4 | == Upgrading to Sphinx 1.4 == |
| Line 12: | Line 12: |
| Line 13: | Line 14: |
| Line 14: | Line 16: |
| Line 18: | Line 21: |
| ## Getting rid of autogenerated .rst stub files | == Getting rid of autogenerated .rst stub files == |
| Line 21: | Line 24: |
| Line 22: | Line 26: |
| Line 23: | Line 28: |
| Line 27: | Line 33: |
| ## Multidoc | == Multidoc == |
| Line 32: | Line 38: |
| Line 33: | Line 40: |
| Line 35: | Line 43: |
| ## Analyzis of the memory footprint of Sphinx (Florent, Robert, Julien) | == Analyzis of the memory footprint of Sphinx (Florent, Robert, Julien) == |
| Line 41: | Line 49: |
| Line 42: | Line 51: |
| Line 44: | Line 54: |
| # Jupyter notebook exporter for Sphinx | == Jupyter notebook exporter for Sphinx == |
| Line 48: | Line 58: |
| # To be discussed with Robert: | == To be discussed with Robert: == |
| Line 52: | Line 62: |
| # Random notes | == Random notes == |
| Line 55: | Line 65: |
| Line 56: | Line 67: |
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.