Opened 6 years ago
Last modified 4 months ago
#20080 new task
Meta-ticket: Sage docbuild
Reported by: | nthiery | Owned by: | |
---|---|---|---|
Priority: | major | Milestone: | sage-9.7 |
Component: | documentation | Keywords: | |
Cc: | egourgoulhon, jhpalmieri, dimpase, klee, schilly | Merged in: | |
Authors: | Reviewers: | ||
Report Upstream: | N/A | Work issues: | |
Branch: | Commit: | ||
Dependencies: | Stopgaps: |
Description (last modified by )
Docbuild tickets:
- #30010 Split sage_setup.docbuild out to a separate distribution (distutils package)
- #31353
sage --docbuild
: Add options to list all documents - #31936 docbuild: Japanese characters creeping into other parts of Sage documentation
- #31366 docbuild: switch from
optparse
toargparse
- #31948 Reimplement parallel docbuild using
make
- #29868 pip-installable packages
sage-doc-html
,sage-doc-pdf
- #30369 Parallel docbuild, cythonization: Use GNU make's POSIX jobserver protocol
- #30475
sage -docbuild
: error building docs of single file with relative imports - #6389 expose building documentation for user modules not in the Sage library
- #30418 Missing PDF icons in the Sage documentation website
- #28376 Shrink Documentation
- #31415 GH Actions workflow that deploys built documentation
- #29868 pip-installable packages sagemath-doc-src, sagemath-doc-inventory, sagemath-doc-html, sagemath-doc-pdf
- https://github.com/sagemath/documentation/issues/24 (Versioned Sage documentation)
Sphinx tickets:
- #31696 Sphinx/docutils update for Sage 9.4
- #27578 Use
sphinx.util.inspect.Signature
notsphinx.ext.autodoc.inspector.formatargspec
- #27164 link sphinx docs of Sage components in reference manual
- #29231 add intersphinx mapping for SciPy
- #27495 Use
sphinx.ext.extlinks
to add Sphinx roles for links to external package docs - #30893 Replace sage autodoc extension by built-in one
- #30894 Add typing info to documentation using
sphinx_autodoc_typehints
See also:
- #20893 Meta-ticket: Improve live documentation in the Jupyter notebook
Overview of Sphinx custom code in Sage's documentation build system
The goal of this ticket is to write an overview of the various bits and pieces of custom Sphinx code in Sage, with the long term goal to see which pieces could be:
- thrown away, using features that are now in Sphinx
- generalized and submitted upstream
- cleaned up
Here is a list of files with their relative roles:
src/sage/docs
__init__.py
: empty file
conf.py
: standard Sphinx configuration file.
src/sage_docbuild (was src/sage_setup/docbuild
)
__init__.py
: top-level docbuilder, contains classes for the various documents (e.g. reference manual).
__main__.py
: stub entry point forsage --docbuild
, callsmain()
from__init__.py
build_options.py
: Parse the option for building.
sphinxbuild.py
: Sage's version of the sphinx-build script
mainly deals with logging and error reporting.
src/sage_docbuild/ext (was src/sage_setup/docbuild/ext
)
inventory_builder.py
:
A customized HTML builder which only generates intersphinx "object.inv" inventory files and pickle files. The documentation files are not written. This is supposed to be used with multidocs below.
multidocs.py
:
The goal of this extension is to manage a multi documentation in Sphinx. To be able to compile Sage's huge documentation in parallel, the documentation is cut into a bunch of independent documentations called "subdocs", which are compiled separately. There is a master document which points to all the subdocs. The intersphinx extension ensures that the cross-link between the subdocs are correctly resolved. However some work is needed to build a global index. This is the goal of multidocs.
More precisely this extension ensures the correct merging of
- the todo list if this extension is activated;
- the python indexes;
- the list of python modules;
- the javascript index;
- the citations.
sage_autodoc.py
This is a patched version of sphinx.ext.autodoc, which started to diverge before 2011. As far as I (Florent) understand, the role here is to
- allows to correctly fetch the Cython doc and argspec
- get correctly the argspec of callable (from the _sage_argspec_ attribute) #9976
- deals correctly with LazyImport? #17455
- In particular document CachedFunction? as a function and not a class instance #9976.
- correctly handles classe aliases and nested classed #7448 #5986
This file probably need to be completely reworked since Sphinx seems to have now various plugin and Mixin.
src/sage/misc
sphinxify.py
script which calls Sphinx to format a single docstring for help from the command line or the notebook. Has its own configuration.
Change History (33)
comment:1 Changed 6 years ago by
- Description modified (diff)
comment:2 Changed 6 years ago by
- Description modified (diff)
comment:3 Changed 6 years ago by
- Description modified (diff)
comment:4 Changed 6 years ago by
- Description modified (diff)
comment:5 Changed 6 years ago by
- Description modified (diff)
comment:6 follow-up: ↓ 10 Changed 6 years ago by
comment:7 Changed 6 years ago by
- Description modified (diff)
comment:8 Changed 6 years ago by
- Description modified (diff)
comment:9 Changed 6 years ago by
- Cc egourgoulhon added
comment:10 in reply to: ↑ 6 Changed 6 years ago by
I would like to mention
sphinxify.py
which is currently part ofsagenb
but should be moved to insidesage
proper ASAP.sphinxify
is called fromsage/misc/sagedoc.py
both at doc building time and run time.
I'm open to PRs, as this seems pretty reasonable - docbuild shouldn't depend on sagenb, though we would still want the doc to work from within it.
comment:11 Changed 6 years ago by
- Description modified (diff)
comment:12 Changed 6 years ago by
Could someone clarify what
This is a slightly hacked-up version of the Sphinx-multidoc plugin
means?
I can't find any reference to a Sphinx multidoc plugin outside of Sage.
comment:14 Changed 6 years ago by
- Description modified (diff)
comment:15 Changed 6 years ago by
I'm having "fun" finally taking the time to fully understand the doc builds system... :)
comment:16 Changed 2 years ago by
it would be a good idea to revise this, or perhaps just start from scratch. It's not clear to me whether most/all of this can be achieved with vanilla Sphinx 3 or 4.
comment:17 Changed 2 years ago by
Related: #30010 - Split sage_setup.docbuild out to a separate distribution (distutils package)
comment:18 Changed 2 years ago by
One of sphinx devs, Takeshi KOMIYA, is going to do a comparison with "native" sphinx for the reference manual - https://github.com/sphinx-doc/sphinx/issues/7891
comment:19 Changed 2 years ago by
Cool!
comment:20 Changed 2 years ago by
- Cc jhpalmieri dimpase added
- Description modified (diff)
- Milestone changed from sage-7.1 to sage-9.3
- Summary changed from Overview of Sphinx custom code in Sage's documentation build system to Meta-ticket: Sage docbuild
comment:21 Changed 2 years ago by
- Description modified (diff)
comment:22 Changed 2 years ago by
- Description modified (diff)
comment:23 Changed 18 months ago by
- Milestone changed from sage-9.3 to sage-9.4
Setting new milestone based on a cursory review of ticket status, priority, and last modification date.
comment:24 Changed 18 months ago by
- Description modified (diff)
comment:25 Changed 14 months ago by
- Description modified (diff)
comment:26 Changed 14 months ago by
- Description modified (diff)
comment:27 Changed 14 months ago by
- Description modified (diff)
comment:28 Changed 14 months ago by
- Description modified (diff)
comment:29 Changed 14 months ago by
- Description modified (diff)
comment:30 Changed 12 months ago by
- Milestone changed from sage-9.4 to sage-9.5
comment:31 Changed 8 months ago by
- Milestone changed from sage-9.5 to sage-9.6
comment:32 Changed 4 months ago by
- Cc klee schilly added
- Description modified (diff)
comment:33 Changed 4 months ago by
- Milestone changed from sage-9.6 to sage-9.7
I would like to mention
sphinxify.py
which is currently part ofsagenb
but should be moved to insidesage
proper ASAP.sphinxify
is called fromsage/misc/sagedoc.py
both at doc building time and run time.