Opened 10 months ago

Last modified 7 days ago

#29868 new enhancement

pip-installable packages sagemath-doc-src, sagemath-doc-inventory, sagemath-doc-html, sagemath-doc-pdf

Reported by: mkoeppe Owned by:
Priority: major Milestone: sage-9.4
Component: build Keywords: sd111
Cc: isuruf, fbissey, arojas, gh-timokau, nbruin, dimpase, jhpalmieri, gh-mwageringel, gh-zlscherr Merged in:
Authors: Reviewers:
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: #31356 Stopgaps:

Status badges

Description (last modified by mkoeppe)

Similar to #29411 + #29950, which made sagelib a pip-installable distribution (which is then installed by the sage-the-distribution script package sagelib), we change the build/installation scheme of the sage documentation.

We create pip-installable packages sagemath-doc-html and sagemath-doc-pdf. By providing wheels on pypi, users can get access to an offline copy of the documentation without having to build it themselves.

We create a package sagemath-doc-inventory, which is in charge of building and installing the inventory files. It is a build dependency of sagemath-doc-html and sagemath-doc-pdf.

All of these packages depend on sagemath-doc-src. It has a build-system dependency on sagelib. An sdist of it consists of SAGE_SRC/doc. A wheel of sagemath-doc-src (and thus an installation) contains a copy of the sources (including the auto-generated rst files) in share/doc/sage/src/ and the doctrees in share/doc/sage/doctrees. The incremental build features of the docbuild will only be active when the package sagemath-doc-src is installed directly using setup.py install, setup.py develop or pip install --editable. In these cases, the doctrees (including environment pickes) are kept in the source directory. pip wheel will always make a from-scratch build of the documentation, eliminating incremental build errors.

The script sage-grepdoc will be provided by sagemath-doc-html.

Follow-up tickets:

  • When installed using pip, the packages provide nbextensions that provide offline help in a Jupyter notebook. This is useful in particular with local notebooks connecting to remote sage kernels (see #30306 (3)).

See also:

  • #30010 - Split sage_setup.docbuild out to a separate package
  • #29097 - build/make/Makefile.in: Rename make targets SPKG-clean to SPKG-uninstall
  • #29231 (add intersphinx mapping for SciPy?) - with discussion about docbuild and inventory files

Change History (21)

comment:1 Changed 10 months ago by mkoeppe

  • Description modified (diff)

comment:2 Changed 9 months ago by mkoeppe

  • Cc nbruin added
  • Description modified (diff)
  • Summary changed from Make sage docbuild a script package to pip-installable packages sage-doc-html, sage-doc-pdf

comment:3 Changed 9 months ago by mkoeppe

  • Description modified (diff)

comment:4 Changed 9 months ago by mkoeppe

  • Cc dimpase jhpalmieri added

comment:5 Changed 9 months ago by mkoeppe

  • Description modified (diff)

comment:6 Changed 9 months ago by mkoeppe

  • Description modified (diff)

comment:7 Changed 8 months ago by mkoeppe

  • Milestone changed from sage-9.2 to sage-9.3

comment:8 Changed 5 months ago by mkoeppe

  • Keywords sd111 added

comment:9 Changed 4 months ago by mkoeppe

  • Description modified (diff)
  • Summary changed from pip-installable packages sage-doc-html, sage-doc-pdf to pip-installable packages sagemath-doc-html, sagemath-doc-pdf

comment:10 Changed 4 months ago by mkoeppe

  • Cc gh-mwageringel added
  • Description modified (diff)

comment:11 Changed 3 months ago by mkoeppe

  • Cc gh-zlscherr added
  • Description modified (diff)
  • Summary changed from pip-installable packages sagemath-doc-html, sagemath-doc-pdf to pip-installable packages sagemath-doc-inventory, sagemath-doc-html, sagemath-doc-pdf

comment:12 Changed 3 months ago by mkoeppe

  • Description modified (diff)
  • Summary changed from pip-installable packages sagemath-doc-inventory, sagemath-doc-html, sagemath-doc-pdf to pip-installable packages sagemath-doc-src, sagemath-doc-inventory, sagemath-doc-html, sagemath-doc-pdf

comment:13 Changed 2 months ago by mkoeppe

  • Dependencies set to #31356

comment:14 Changed 2 months ago by mkoeppe

  • Milestone changed from sage-9.3 to sage-9.4

Setting new milestone based on a cursory review of ticket status, priority, and last modification date.

comment:15 Changed 8 days ago by mkoeppe

Input and help from docbuild experts is very welcome.

comment:16 follow-ups: Changed 8 days ago by mkoeppe

Some questions:

  • Who generates files such as src/doc/en/reference/monoids/sage/monoids/free_monoid.rst, and should they be part of what sagemath-doc-src installs (and thus ships with the wheel)?
  • Is there a way to only generate the doctrees but not build HTML or PDF?
  • Do the HTML and PDF builds need to be able to run the Sage library, or can they build these formats if given only the doctrees?

comment:17 in reply to: ↑ 16 ; follow-up: Changed 8 days ago by fbissey

Replying to mkoeppe:

Some questions:

  • Is there a way to only generate the doctrees but not build HTML or PDF?

I do believe there is a sphinx option for doing just that.

  • Do the HTML and PDF builds need to be able to run the Sage library, or can they build these formats if given only the doctrees?

As far as I know they need to be able to run the sage library. In particular all graphs/plots are generated during the documentation build.

comment:18 in reply to: ↑ 17 Changed 7 days ago by fbissey

Replying to fbissey:

Replying to mkoeppe:

Some questions:

  • Is there a way to only generate the doctrees but not build HTML or PDF?

I do believe there is a sphinx option for doing just that.

I cannot find such an option anymore. If it existed. There is an option to say where the doctrees should be stored and found, but nothing on producing it in isolation.

comment:19 Changed 7 days ago by jhpalmieri

Well, ./sage --docbuild all inventory builds the inventory files and the doctree files, but not html or pdf.

comment:20 in reply to: ↑ 16 Changed 7 days ago by jhpalmieri

Replying to mkoeppe:

Some questions:

  • Who generates files such as src/doc/en/reference/monoids/sage/monoids/free_monoid.rst, and should they be part of what sagemath-doc-src installs (and thus ships with the wheel)?

The autodoc procedure does this, with sage/monoids/free_monoid.py as input. (Edit: or maybe just src/doc/en/reference/monoids/index.rst as input?) I'm not sure precisely how this is done, but the file sage_docbuild/ext/sage_autodoc.py is certainly relevant. (This is Sage's fork of the Sphinx autodoc module.)

Last edited 7 days ago by jhpalmieri (previous) (diff)

comment:21 Changed 7 days ago by jhpalmieri

No, I'm wrong about that. It's done in sage_docbuild/__init__.py, in the write_auto_rest_file method.

Last edited 7 days ago by jhpalmieri (previous) (diff)
Note: See TracTickets for help on using tickets.