We wish to link to external packages' documentation:

• if the package documentation is installed locally in the Sage distribution, using the file link
• in downstream packaging, using a file link appropriate for the doc installation scheme of the system (without having to patch the documentation)
• if it is not available locally, using an http link to an online version of the package's documentation.

To this end, we use the sphinx.ext.extlinks facility, for which we already have infrastructure in sage.misc.sagedoc, assigning a Sphinx role to every external document.

We use a systematic naming scheme for these roles: :spkg_SPKG_DOC: where DOC is usually just doc but if a package has several manuals, it can be used to distinguish them.

In this ticket, we do this for the documents covered by a previous iteration of this ticket:

• :spkg_gc_doc: GC garbage collector <@SAGE_SHARE@/doc/gc/overview.html>_
• :spkg_giac_doc: Giac/Xcas documentation <@SAGE_SHARE@/doc/giac/index.html>_ https://www-fourier.ujf-grenoble.fr/~parisse/giac/doc/en/cascmd_en/cascmd_en.html
• :spkg_ppl_doc: PPL User manual <@SAGE_SHARE@/doc/ppl/ppl-user-1.2-html/index.html>_ https://www.bugseng.com/products/ppl/documentation/user/ppl-user-1.2-html/index.html
• :spkg_pplpy_doc: Python Wrapper for PPL (pplpy) <@SAGE_SHARE@/doc/pplpy/index.html>_
• :spkg_singular_doc: Singular User Manual <@SAGE_SHARE@/singular/html/index.htm>_ https://www.singular.uni-kl.de/Manual/4-2-0/index.htm
• spkg_maxima_doc: Introduction to Maxima <@SAGE_SHARE@/maxima/@MAXIMA_VERSION@/doc/html/intromax.html>_ https://maxima.sourceforge.io/docs/manual/maxima_0.html

The location of some of the locally installed documentation files can be determined at runtime, see #27495 comment:58 for maxima.
This should probably go through sage.feature.

Related:

• add intersphinx mapping for SciPy #29231 add intersphinx mapping for SciPy
• https://groups.google.com/g/sage-devel/c/oWkFwhinoMc/m/JpighcELBgAJ
• pip-installable packages sagemath-doc-src, sagemath-doc-inventory, sagemath-doc-html, sagemath-doc-pdf #29868 pip-installable packages sagemath-doc-src, sagemath-doc-inventory, sagemath-doc-html, sagemath-doc-pdf

CC: @tobihan @kcrisman @kiwifb @embray @haraldschilly @mkoeppe @antonio-rojas @mwageringel @videlec

Component: documentation

Keywords: sd111

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