#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:
---------------------------------+------------------------
Description changed by jdemeyer:
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 in {{{src/doc/common}}} with their relative
> roles:
>
> - `__init__.py`:
>
> empty file
>
> - `conf.py`
>
> Here is a list of files in {{{srcsrc/sage_setup/docbuild}}} with their
> relative roles:
>
> - `builder.py`
>
> - `build_options.py`
>
> - `custom-sphinx-build.py`
>
> - `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.
>
> - `ext/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
> - the todo list if this extension is activated;
> - the python indexes;
> - the list of python modules;
> - the javascript index;
> - the citations.
>
> - `ext/sage_autodoc.py`
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 in {{{src/doc/common}}} with their relative roles:
- `__init__.py`: empty file
- `conf.py`
Here is a list of files in {{{srcsrc/sage_setup/docbuild}}} with their
relative roles:
- `__init__.py`: top-level docbuilder, contains classes
- `__main__.py`: entry point for `sage --docbuild`, calls `main()` from
`__init__.py`
- `build_options.py`
- `sphinxbuild.py`
- `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.
- `ext/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
- the todo list if this extension is activated;
- the python indexes;
- the list of python modules;
- the javascript index;
- the citations.
- `ext/sage_autodoc.py`
--
--
Ticket URL: <http://trac.sagemath.org/ticket/20080#comment:5>
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.
