#6495: Build the reference manual incrementally
-----------------------------+----------------------------------------------
Reporter: mpatel | Owner: tba
Type: enhancement | Status: needs_review
Priority: major | Milestone: sage-4.7.2
Component: documentation | Keywords:
Work_issues: | Upstream: N/A
Reviewer: Volker Braun | Author: Mitesh Patel, John Palmieri
Merged: | Dependencies: 11251
-----------------------------+----------------------------------------------
Description changed by jhpalmieri:
Old description:
> Building the Sage reference manual can use significant computer
> resources. Easing the burden could speed up Sage development.
>
> Apply:
>
> - [attachment:trac_6495-subdivide-ref-manual.patch]
>
> Also, before building the docs, it's probably a good idea to delete the
> documentation output directory: {{{rm -rf
> SAGE_ROOT/devel/sage/doc/output}}}.
New description:
Building the Sage reference manual can use significant computer resources.
Easing the burden could speed up Sage development.
The patch is large, but most of it consists of moving files from one
location to another, as described below. A summary of the changes:
Changes in `doc/en/reference` — this is where the size of the patch comes
from, although the changes are pretty simple:
- rearrange the directory doc/en/reference: for each file like
algebras.rst, create a subdirectory `algebras` and move `algebras.rst` to
`algebras/index.rst`. Also create a file `algebras/conf.py` for the build
configuration. All of these new conf.py files are identical. Deal with
the contents of the directory `reference/media` similarly, moving the
pictures to the appropriate subdirectory.
- modify `reference/index.rst` to point to these new files.
- reorganize `reference/index.rst` so it is arranged, at least somewhat,
by topic.
- add intersphinx to `conf.py` — see below. Also add the new
subdirectories to the list `exclude_trees`.
- new file `conf_sub.py`, configuration for the pieces of the
documentation (as opposed to the main `conf.py`, which is for building
`reference/index.rst`). This file is imported by each of the files
`SUBDIRECTORY/conf.py`.
Changes to `doc/common/builder.py`:
- add code to build the reference manual in sections, and also to build
the sections in parallel. The reference manual ought to be built twice to
resolve references now, so typing "sage -docbuild all html" will build it
twice (along with all of the other documents, of course). "sage -docbuild
reference html" will just build it once. You can also run "sage -docbuild
reference/combinat html", for example, to just build one part of the
manual.
- the different parts of the manual are separate documents as far as
sphinx is concerned, so allow them to reference each other using the
"intersphinx" extension. (This is why we need to build it twice: the
first pass assembles the intersphinx databases, the second pass uses the
databases to create the references correctly.)
- to accomodate the changes in #11251, which don't seem to be easily
compatible with intersphinx, search through the output files looking for
"todo" items, and accumulate them in one master "todo" list.
- for pdf format, since it now produces 30 different pdf files, write an
html file which links to each of them.
Other changes:
- `doc/common/conf.py`: add the intersphinx extension to the build
process.
- `doc/common/themes/sage/layout.html`: fix a bug where clicking the Sage
logo in the upper left corner of the docs wouldn't take you to the right
place, at least in the local documentation.
- `doc/common/themes/sageref/`: add a new theme for the pieces of the
reference manual. This is almost identical to the "sage" theme, except
for a little tinkering to the links along the top and bottom lines.
- in the main Sage library, change a few pathnames to media files in the
reference manual, since those files have been moved.
- `spkg-dist`: when building the main sage spkg file, delete all of the
autogenerated files from the doc directory. This is important because if
some autogenerated files from before the patch are still present after the
patch, the docbuild process can occasionally get confused. It also saves
some space, making a smaller spkg file.
- make the necessary changes to .hgignore and MANIFEST.in to deal with
the relocated files.
--------
Apply:
- [attachment:trac_6495-subdivide-ref-manual.patch]
Also, before building the docs, it's probably a good idea to delete the
documentation output directory: {{{rm -rf
SAGE_ROOT/devel/sage/doc/output}}}.
--
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/6495#comment:21>
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 post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/sage-trac?hl=en.
