|
Size: 2227
Comment:
|
Size: 2262
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 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 7: | Line 7: |
| ## Upgrading to Sphinx 1.4 | == Upgrading to Sphinx 1.4 == |
| 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 18: | Line 18: |
| ## Getting rid of autogenerated .rst stub files | == Getting rid of autogenerated .rst stub files == |
| Line 21: | 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 27: | Line 27: |
| ## Multidoc | == Multidoc == |
| Line 30: | 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 |
|
| Line 31: | Line 34: |
| - 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) |
== Analyzis of the memory footprint of Sphinx (Florent, Robert, Julien) == |
| Line 38: | 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). 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. |
|
| Line 39: | Line 42: |
| - 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 |
== Jupyter notebook exporter for Sphinx == |
| Line 48: | Line 46: |
| # To be discussed with Robert: | == To be discussed with Robert: == * Error reporting of Sphinx when documenting API. How to locate the error.? |
| Line 50: | Line 49: |
| - 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. |
== 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. |
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.