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 Meta-ticket: Use system Jupyter notebook / JupyterLab #30306 (3)).
  • https://jupyter-notebook.readthedocs.io/en/stable/examples/Notebook/Distributing%20Jupyter%20Extensions%20as%20Python%20Packages.html
• Or alternatively as a JupyterLab extension
  • https://jupyterlab.readthedocs.io/en/stable/extension/extension_dev.html

See also:

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

Depends on #33852

CC: @isuruf @kiwifb @antonio-rojas @timokau @nbruin @dimpase @jhpalmieri @mwageringel @zlscherr

Component: build

Keywords: sd111

Issue created by migration from https://trac.sagemath.org/ticket/29868