#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, 11298
-----------------------------+----------------------------------------------
Changes (by jhpalmieri):
* dependencies: 11251 => 11251, 11298
Old 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}}}.
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-part1-moving-files.patch] — this moves
'algebras.rst' to 'algebras/index.rst', and similarly for all other files.
It adds `.. include:: ../footer.txt` to the end of each of these files,
and it removes any cross-referencing information like `.. _ch:groups:`,
since that doesn't work anymore with the new structure. It also creates
identical files 'DIR/conf.py' in each of the new subdirectories of
doc/en/reference, except for doc/en/algebras/conf.py. That file is
created in the next patch so that you can focus on reviewing just the
second patch.
- [attachment:trac_6495-part2-everything-else.patch] — this does
everything else; in other words, all of the important content is in this
patch.
Before building the docs, you should delete the documentation output
directory: {{{rm -rf SAGE_ROOT/devel/sage/doc/output}}}.
--
Comment:
Here's a new version, with #11298 as a new dependency. (It may apply
without #11298, perhaps with fuzz.) To help with reviewing, I've broken
the patch into two pieces, as explained in the ticket description.
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/6495#comment:22>
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.
