Opened 10 years ago

Last modified 6 years ago

#6495 closed enhancement

Build the reference manual incrementally — at Version 8

Reported by: mpatel Owned by: tba
Priority: major Milestone: sage-5.8
Component: documentation Keywords: days38
Cc: jhpalmieri, leif, niles, hivert, mguaypaq, mhansen Merged in:
Authors: Mitesh Patel Reviewers:
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Description (last modified by mpatel)

Building the Sage reference manual can use significant computer resources. Easing the burden could speed up Sage development.

Change History (11)

Changed 10 years ago by mpatel

Experimental.

comment:1 Changed 10 years ago by mpatel

  • Authors set to Mitesh Patel
  • Cc jhpalmieri added
  • Summary changed from Break up the PDF reference manual into smaller pieces to [with patch, needs work] Break up the PDF reference manual into smaller pieces

The attached patch is experimental. Notes:

  • sage -docbuild reference pdf fails to build arithgroup.pdf, apparently because of the math macro \ZZ in the title. Unfortunately, I don't know how to fix this.
  • Since it replaces the top level PDF file with several smaller files, it breaks the patch at #4460.
  • It's not clear what happens to cross-ReST document links. I'll try to investigate.

comment:2 Changed 10 years ago by mpatel

On cross-PDF document links: It seems that Sphinx does not produce these. This may OK, since file:// URLs can break easily.

comment:3 Changed 10 years ago by mpatel

On the \ZZ in arithgroup.tex: It seems the problem stems from \@title in

    \ifsphinxpdfoutput
      \begingroup
      % This \def is required to deal with multi-line authors; it               
      % changes \\ to ', ' (comma-space), making it pass muster for             
      % generating document info in the PDF file.                               
      \def\\{, }
      \pdfinfo{
        /Author (\@author)
        /Title (\@title)
      }
      \endgroup
    \fi

in Sphinx's manual.cls. For some reason, the \math* font commands do not work in this context. I gather that \mathbf is preferred, but one workaround is to use

Arithmetic Subgroups of `{\rm SL}_2({\bf Z})`

in place of

Arithmetic Subgroups of `{\rm SL}_2(\ZZ)`

in arithgroup.rst.

Changed 10 years ago by mpatel

Another approach. Depends on #7549. Still experimental. This patch only. sage repo.

comment:4 Changed 10 years ago by mpatel

  • Priority changed from minor to major
  • Report Upstream set to N/A
  • Summary changed from [with patch, needs work] Break up the PDF reference manual into smaller pieces to Build the reference manual incrementally
  • Type changed from defect to enhancement

The new patch may make it possible to build and update reference manual chapters semi-independently. I think we can use the intersphinx extension to fix the cross-chapter references. But we'll need to build the manual twice, a la LaTeX.

To build just a chapter, try, e.g.,

sage -docbuild reference/algebras html -juiv3

Still to do:

  • Make a combined index page and search page.
  • Check that PDF generation works.
  • Combine chapter PDF files into one large [optional] PDF file (with pdfjam's pdfjoin)?
  • Use a specific LaTeX doc title in each conf.py.
  • Fix the "Arithmetic Subgroups" heading on the top-level page.
  • Use a visual, 2D layout for the top-level page? Group by general area? Add icons?
  • Get a reply from sphinx-dev about making relative paths work.
  • Build docs in parallel (cf. #6255) with multiprocessing?
  • Replace the "website" PDF link?
  • User-friendliness improvements.
  • Encourage more compact chapters? It seems that "Combinatorics" takes the most time and memory.
  • ...

comment:5 Changed 10 years ago by mpatel

Another important item:

  • Use just one _static directory for the manual, not 50+!

comment:6 Changed 10 years ago by mpatel

If this approach is viable, I suggest leaving many (most?) of the "To Do" items for other tickets.

comment:7 Changed 10 years ago by mpatel

While I'm here:

  • Copy PDFs from output/latex/ to output/pdf, so that make all-pdf, at least, doesn't do unnecessary work?

comment:8 Changed 10 years ago by mpatel

  • Description modified (diff)

Changed 10 years ago by mpatel

PDF fixes. This patch only. sage repo.

Note: See TracTickets for help on using tickets.