#6495: Build the reference manual incrementally
-----------------------------+----------------------------------------------
Reporter: mpatel | Owner: tba
Type: enhancement | Status: needs_work
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
-----------------------------+----------------------------------------------
Changes (by newvalueoldvalue):
* dependencies: => 11251
* author: Mitesh Patel => Mitesh Patel, John Palmieri
Comment:
Replying to [comment:13 vbraun]:
>
> I tried the patch on Sage-4.7.1.alpha4 without any other patches
applied:
> * Only the main page has proper css. For example,
`html/en/reference/cmd/index.html` refers to `_static/sage.css` but the
correct path would be `../_static/sage.css`.
This was a mistake in the previous version: it was supposed to create a
link from `reference/_static` to `reference/cmd/_static`. Now it should
work.
> * patch conflicts with #11251 (todo extension). Given that the latter
is already positively reviewed, maybe this ticket could be rebased on top
of it?
Good point. This raises another problem: intersphinx doesn't easily pass
todo lists between different documents, so I don't know how to get a
master todo list for the Sage library. Right now, I've put the todolist
for each module after its table of contents. I think combinat is the only
module with any actual to do elements.
> * During the sage build, I think we should then run the docbuilder
twice for the reference manual. Perhaps this should always be done for
`sage -docbuild all`.
Done: {{{sage -docbuild all}}} now builds the reference manual twice. I
also added a few print statements to the docbuild process.
> * Can we make output less verbose? The whole intersphinx output
scrolled forever off my screen. Ideally, an interspinx failure to find an
inventory file would only add one extra line at the end of the build along
the lines of "You should re-run docbuild to get references right."
I've tried to do this when doing {{{sage -docbuild all}}} and not in
general, but it may be suppressing too much output. (In the first pass,
all warnings are suppressed, including intersphinx warnings, and in the
second pass, any warnings should be printed. But in the second pass, it's
just rewriting output, taking intersphinx links into account -- it's not
reading the sources a second time, so it doesn't produce warnings about
missing bibliographic references.)
Other issues:
- In PDF output, this produces one PDF file for each module, but there is
no "master" file linking to them. I hope we can create one. Should it be
an html file or a PDF file?
- We could perhaps speed things up more by breaking the {{{combinat}}}
module, which is by far the largest, into several pieces. This can happen
on another ticket.
- I've reorganized the main index for the reference manual, grouping
modules together by topic. I hope it's easier to find things this way. I
wonder if we can get intersphinx to produce a master index for all of the
documents...
- in the old version, at least on my computer, when I clicked on the Sage
logo in the top left corner, it wasn't taking me to the right place. I've
fixed that. Along the same lines, with the new reorganization, the other
links on the top line look a little funny to me in the reference manual.
They looked worse before and I've tried to clean them up, but maybe they
could use more work?
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/6495#comment:14>
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.
