#20080: Overview of Sphinx custom code in Sage's documentation build system
---------------------------------+------------------------
Reporter: nthiery | Owner:
Type: task | Status: new
Priority: major | Milestone: sage-7.1
Component: documentation | Resolution:
Keywords: | Merged in:
Authors: | Reviewers:
Report Upstream: N/A | Work issues:
Branch: | Commit:
Dependencies: | Stopgaps:
---------------------------------+------------------------
Old description:
> 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/doc/common'''
>
> - `__init__.py`: empty file
>
> - `conf.py`: standard Sphinx configuration file.
>
> '''src/sage_setup/docbuild'''
>
> - `__init__.py`: top-level docbuilder, contains classes for the various
> documents (e.g. reference manual).
>
> - `__main__.py`: stub entry point for `sage --docbuild`, calls `main()`
> 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_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`:
>
> This is a slightly hacked-up version of the Sphinx-multidoc plugin
>
> 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
>
> 1. the todo list if this extension is activated;
> 1. the python indexes;
> 1. the list of python modules;
> 1. the javascript index;
> 1. 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
>
> 1. allows to correctly fetch the Cython doc and argspec
> 1. get correctly the argspec of callable (from the _sage_argspec_
> attribute) #9976
> 1. deals correctly with LazyImport #17455
> 1. In particular document CachedFunction as a function and not a
> class
> instance #9976.
> 1. 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.
>
> '''sagenb/sagenb/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.
New description:
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/doc/common'''
- `__init__.py`: empty file
- `conf.py`: standard Sphinx configuration file.
'''src/sage_setup/docbuild'''
- `__init__.py`: top-level docbuilder, contains classes for the various
documents (e.g. reference manual).
- `__main__.py`: stub entry point for `sage --docbuild`, calls `main()`
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_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
1. the todo list if this extension is activated;
1. the python indexes;
1. the list of python modules;
1. the javascript index;
1. 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
1. allows to correctly fetch the Cython doc and argspec
1. get correctly the argspec of callable (from the _sage_argspec_
attribute) #9976
1. deals correctly with LazyImport #17455
1. In particular document CachedFunction as a function and not a
class
instance #9976.
1. 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.
'''sagenb/sagenb/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.
--
Comment (by jdemeyer):
Fixed :-)
--
Ticket URL: <https://trac.sagemath.org/ticket/20080#comment:13>
Sage <http://www.sagemath.org>
Sage: Creating a Viable Open Source Alternative to Magma, Maple, Mathematica,
and MATLAB
--
You received this message because you are subscribed to the Google Groups
"sage-trac" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at https://groups.google.com/group/sage-trac.
For more options, visit https://groups.google.com/d/optout.
