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: |
Description (last modified by )
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
nbextension
s 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:
Change History (21)
comment:1 Changed 10 months ago by
- Description modified (diff)
comment:2 Changed 9 months ago by
- 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
- Description modified (diff)
comment:4 Changed 9 months ago by
- Cc dimpase jhpalmieri added
comment:5 Changed 9 months ago by
- Description modified (diff)
comment:6 Changed 9 months ago by
- Description modified (diff)
comment:7 Changed 8 months ago by
- Milestone changed from sage-9.2 to sage-9.3
comment:8 Changed 5 months ago by
- Keywords sd111 added
comment:9 Changed 4 months ago by
- 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
- Cc gh-mwageringel added
- Description modified (diff)
comment:11 Changed 3 months ago by
- 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
- 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
- Dependencies set to #31356
comment:14 Changed 2 months ago by
- Milestone changed from sage-9.3 to sage-9.4
comment:15 Changed 8 days ago by
Input and help from docbuild experts is very welcome.
comment:16 follow-ups: ↓ 17 ↓ 20 Changed 8 days ago by
Some questions:
- Who generates files such as
src/doc/en/reference/monoids/sage/monoids/free_monoid.rst
, and should they be part of whatsagemath-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: ↓ 18 Changed 8 days ago by
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
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
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
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 whatsagemath-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.)
comment:21 Changed 7 days ago by
No, I'm wrong about that. It's done in sage_docbuild/__init__.py
, in the write_auto_rest_file
method.
Setting new milestone based on a cursory review of ticket status, priority, and last modification date.