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: |
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)). - Or alternatively as a JupyterLab extension
See also:
Change History (29)
comment:1 Changed 2 years ago by
- Description modified (diff)
comment:2 Changed 23 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 23 months ago by
- Description modified (diff)
comment:4 Changed 23 months ago by
- Cc dimpase jhpalmieri added
comment:5 Changed 23 months ago by
- Description modified (diff)
comment:6 Changed 23 months ago by
- Description modified (diff)
comment:7 Changed 23 months ago by
- Milestone changed from sage-9.2 to sage-9.3
comment:8 Changed 19 months ago by
- Keywords sd111 added
comment:9 Changed 19 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 18 months ago by
- Cc gh-mwageringel added
- Description modified (diff)
comment:11 Changed 17 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 17 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 17 months ago by
- Dependencies set to #31356
comment:14 Changed 17 months ago by
- Milestone changed from sage-9.3 to sage-9.4
comment:15 Changed 15 months ago by
Input and help from docbuild experts is very welcome.
comment:16 follow-ups: ↓ 17 ↓ 20 Changed 15 months 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 15 months 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 15 months 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 15 months 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 15 months 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 15 months ago by
No, I'm wrong about that. It's done in sage_docbuild/__init__.py
, in the write_auto_rest_file
method.
comment:22 Changed 11 months ago by
- Milestone changed from sage-9.4 to sage-9.5
comment:23 Changed 8 months ago by
- Dependencies changed from #31356 to #31356, #32713
comment:24 Changed 6 months ago by
- Milestone changed from sage-9.5 to sage-9.6
comment:25 Changed 6 months ago by
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
- Description modified (diff)
comment:27 Changed 4 months ago by
- Milestone changed from sage-9.6 to sage-9.7
comment:28 Changed 6 weeks ago by
- Dependencies changed from #31356, #32713 to #33852
comment:29 Changed 6 weeks ago by
- Description modified (diff)
Setting new milestone based on a cursory review of ticket status, priority, and last modification date.