#6495: Build the reference manual incrementally
-----------------------------+----------------------------------------------
Reporter: mpatel | Owner: tba
Type: enhancement | Status: needs_work
Priority: major | Milestone:
Component: documentation | Keywords:
Work_issues: | Upstream: N/A
Reviewer: | Author: Mitesh Patel
Merged: | Dependencies:
-----------------------------+----------------------------------------------
Comment(by jhpalmieri):
Here's a new patch, rebased to Sage 4.7.1.alpha4. This implements
parallel building, and it provides a great speedup, at least on systems
with lots of processors. For example, on sage.math, the time to execute
{{{sage -docbuild reference html -j}}} went from about 18 minutes to just
under 2 minutes. The main idea is to build each module of the reference
manual separately, and use the Sphinx
[http://sphinx.pocoo.org/ext/intersphinx.html intersphinx] extension to
handle cross-references (so {{{:class:`blah`}}} will work in the algebras
module, even if {{{blah}}} is defined in the rings module).
Remaining issues:
- The new build uses up more disk space than the old, by about 120
megabytes. I don't know if anything can be done about this, and I also
don't think it's a big deal. (With the previous patch, it took about 1
gigabyte more, but the more recent patch manages to cut that down: in the
previous patch, the {{{_static}}} subdirectory of the documentation was
being copied, once for each module of the reference manual, and with the
new version, a symlink is used instead.)
- There are now some missing bibliographic references: at some point in
the past, people have gone through the documentation and unified the
references, but this means that references in one module are not seen by
any other. This can be fixed just by copying the references to the module
where they're used. For example: CMR05 is referenced somewhere in the
module on polynomial rings, but the actual item is described in
{{{crypto/mq/sr.py}}}.
- The cross-referencing in intersphinx is not perfect; in particular, it
doesn't seem to work after building the documents once, it needs to have
the full doctree "inventory" for any module available before resolving
references to that module. Since the inventory files are built alongside
the documentation, this means it has to be built twice (as far as I can
tell) before cross-all of the references work. We could try to figure out
dependencies and make sure that if module A is referenced in module B,
then A is built first, but that seems complicated, and there is no reason
for there not to be circular references. I'm tempted to just allow broken
cross-references. For the docs on the web site, we would have to make
sure they got built twice.
- There is a main index for the reference manual, but once you click on
any entry (like "Cryptography"), you get to that module's index, and there
is no link taking you back to the main index. There ought to be a way to
fix this, but I haven't figured it out yet.
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/6495#comment:12>
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.
