Opened 2 years ago

Last modified 6 weeks 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.7
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: #33852 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:

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 (29)

comment:1 Changed 2 years ago by mkoeppe

  • Description modified (diff)

comment:2 Changed 23 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 23 months ago by mkoeppe

  • Description modified (diff)

comment:4 Changed 23 months ago by mkoeppe

  • Cc dimpase jhpalmieri added

comment:5 Changed 23 months ago by mkoeppe

  • Description modified (diff)

comment:6 Changed 23 months ago by mkoeppe

  • Description modified (diff)

comment:7 Changed 23 months ago by mkoeppe

  • Milestone changed from sage-9.2 to sage-9.3

comment:8 Changed 19 months ago by mkoeppe

  • Keywords sd111 added

comment:9 Changed 19 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 18 months ago by mkoeppe

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

comment:11 Changed 17 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 17 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 17 months ago by mkoeppe

  • Dependencies set to #31356

comment:14 Changed 17 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 15 months ago by mkoeppe

Input and help from docbuild experts is very welcome.

comment:16 follow-ups: Changed 15 months 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 15 months 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 15 months 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 15 months 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 15 months 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 15 months ago by jhpalmieri (previous) (diff)

comment:21 Changed 15 months 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 15 months ago by jhpalmieri (previous) (diff)

comment:22 Changed 11 months ago by mkoeppe

  • Milestone changed from sage-9.4 to sage-9.5

comment:23 Changed 8 months ago by mkoeppe

  • Dependencies changed from #31356 to #31356, #32713

comment:24 Changed 6 months ago by mkoeppe

  • Milestone changed from sage-9.5 to sage-9.6

comment:25 Changed 6 months ago by mkoeppe

According to https://trac.sagemath.org/ticket/33064#comment:19, there is no need to install doctrees in SAGE_LOCAL, not even for introspection (sage.misc.sphinxify)

comment:26 Changed 6 months ago by slelievre

  • Description modified (diff)

comment:27 Changed 4 months ago by mkoeppe

  • Milestone changed from sage-9.6 to sage-9.7

comment:28 Changed 6 weeks ago by mkoeppe

  • Dependencies changed from #31356, #32713 to #33852

comment:29 Changed 6 weeks ago by mkoeppe

  • Description modified (diff)
Note: See TracTickets for help on using tickets.