|
Size: 2280
Comment:
|
Size: 2262
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 5: | Line 5: |
| - 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 | 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 |
| Line 12: | Line 12: |
- native support parallelism - removal of some hacks for Cython support - ... |
* native support parallelism * removal of some hacks for Cython support * ... |
| Line 24: | Line 21: |
- simpler build system (no need to maintain essentially duplicate information) - more robust build w.r.t. deleting python files - cleaner, ... |
* simpler build system (no need to maintain essentially duplicate information) * more robust build w.r.t. deleting python files * cleaner, ... |
| Line 36: | Line 30: |
- 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 |
* 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 |
| Line 46: | Line 37: |
- 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). |
* 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). |
| Line 49: | Line 39: |
- 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. |
* 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. |
| Line 59: | Line 47: |
- Error reporting of Sphinx when documenting API. How to locate the error.? |
* Error reporting of Sphinx when documenting API. How to locate the error.? |
| Line 63: | Line 50: |
- 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. |
* 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. |
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.