#6495: Build the reference manual incrementally
---------------------------------------------------------------+------------
Reporter: mpatel | Owner:
jdemeyer
Type: enhancement | Status:
needs_review
Priority: major | Milestone:
sage-5.7
Component: documentation | Resolution:
Keywords: days38 | Work issues:
Report Upstream: N/A | Reviewers:
Volker Braun, Florent Hivert
Authors: Mitesh Patel, John Palmieri, Florent Hivert | Merged in:
Dependencies: 5.7.beta2 + #13064, #8327, #13891 | Stopgaps:
---------------------------------------------------------------+------------
Old description:
> Building the Sage reference manual can take a significant amount of time.
> Decreasing this time 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.
> - make the necessary changes to .hgignore and MANIFEST.in to deal with
> the relocated files.
>
> --------
>
> The html docs for Sage 5.4.rc2,
> [http://sage.math.washington.edu/home/palmieri/misc/6495/html/ html
> without MathJax],
> [http://sage.math.washington.edu/home/palmieri/misc/6495-jsmath/html/
> html with MathJax], and
> [http://sage.math.washington.edu/home/palmieri/misc/6495/pdf/ pdf],
> built after applying the patches here.
>
> --------
>
> '''Apply''':
> - [attachment:trac_6495-part1-moving-files.patch] (or run
> [attachment:trac_6495-script-jhp.sh])
> - [attachment:trac_6495-part2-everything-else.patch]
> - [attachment:trac_6495-part3-the-remaining-vs-5.7.beta4.patch]
> - [attachment:trac_6495-part4-interrupts.patch]
> - [attachment:trac-6495_silence_warning-fh.v2.patch].
> - [attachment:trac_6495-redirect_html.2.patch].
> - [attachment:trac_6495-docstrings.patch].
> - [attachment:trac_6495_separate_inventory.patch]
> - [attachment:trac_6495_fixes.patch]
> - [attachment:trac_6495-filtering.patch]
>
> --------
>
> Before building the docs, you should delete the documentation output
> directory: {{{rm -rf SAGE_ROOT/devel/sage/doc/output}}}. To test this,
> you should run `sage --docbuild all html` and `sage --docbuild all pdf`.
> (Note: just running `sage --docbuild reference html` will probably
> produce many warnings. If you run it a second time, the warnings should
> go away.)
New description:
Building the Sage reference manual can take a significant amount of time.
Decreasing this time 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.
- make the necessary changes to .hgignore and MANIFEST.in to deal with
the relocated files.
--------
The html docs for Sage 5.4.rc2,
[http://sage.math.washington.edu/home/palmieri/misc/6495/html/ html
without MathJax],
[http://sage.math.washington.edu/home/palmieri/misc/6495-jsmath/html/ html
with MathJax], and
[http://sage.math.washington.edu/home/palmieri/misc/6495/pdf/ pdf],
built after applying the patches here.
--------
'''Apply''':
- [attachment:trac_6495-part1-moving-files-link.patch] (or run
[attachment:trac_6495-script-jhp-link.sh])
- [attachment:trac_6495-part2-everything-else.patch]
- [attachment:trac_6495-part3-the-remaining-vs-5.7.beta4.patch]
- [attachment:trac_6495-part4-interrupts.patch]
- [attachment:trac-6495_silence_warning-fh.v2.patch].
- [attachment:trac_6495-redirect_html.2.patch].
- [attachment:trac_6495-docstrings.patch].
- [attachment:trac_6495_separate_inventory.patch]
- [attachment:trac_6495_fixes.patch]
- [attachment:trac_6495-filtering.patch]
--------
Before building the docs, you should delete the documentation output
directory: {{{rm -rf SAGE_ROOT/devel/sage/doc/output}}}. To test this, you
should run `sage --docbuild all html` and `sage --docbuild all pdf`.
(Note: just running `sage --docbuild reference html` will probably produce
many warnings. If you run it a second time, the warnings should go away.)
--
Comment (by jhpalmieri):
Good question. The files `conf.py` are pretty minimal, and most of the
content is in `en/reference/conf_sub.py`, which is imported by each
`conf.py` file. So the idea is that to maintain it, you would just need to
modify `conf_sub.py`. But here's a new version of the part 1 patch and the
script which creates links directly from `en/reference/MODULE/conf.py`
pointing to `en/reference/conf_sub.py`. This seems to work. I'll check on
!OpenSolaris to make sure there's nothing strange going on there.
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/6495#comment:229>
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 http://groups.google.com/group/sage-trac?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.
