add intersphinx mapping for SciPy

[mwageringel]

This ticket adds an intersphinx mapping for Sphinx to resolve hyperlinks to the Scipy documentation.

With this change, Sphinx fetches the Scipy inventory file objects.inv from https://docs.scipy.org/doc/scipy/reference/ during the docbuild. It links against the latest version of the Scipy documentation to keep it simple.

If the download fails, for example when building Sage without internet access, the docbuild will still succeed, but the Scipy cross-links will not be resolved.

CC: @embray @jhpalmieri

Component: documentation

Author: Markus Wageringel

Branch/Commit: u/gh-mwageringel/29231 @ d19232d

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

[mwageringel]

Commit: 3bd5293

[mwageringel]

comment:1

This merges cleanly with #17405.

If this gets accepted, the same could be applied to numpy.

---

New commits:

3bd5293

29231: add intersphinx mapping for scipy

[mwageringel]

Author: Markus Wageringel

[mwageringel]

Branch: u/gh-mwageringel/29231

[mwageringel]

Description changed:

--- 
+++ 
@@ -1,4 +1,3 @@
 This ticket adds an intersphinx mapping for Sphinx to resolve hyperlinks to the Scipy documentation.
 
-With this change, Sphinx fetches the Scipy inventory file `objects.inv` from https://docs.scipy.org/doc/scipy/reference/ during the docbuild. (If this fails for some reason, the docbuild will also fail.)
-
+With this change, Sphinx fetches the Scipy inventory file `objects.inv` from https://docs.scipy.org/doc/scipy/reference/ during the docbuild. (If this fails for some reason, the docbuild will also fail.) It links against the latest version of the Scipy documentation to keep it simple.

[jhpalmieri]

comment:3

Sage should in principle build without an internet connection, so I am not in favor of this approach. (“If this fails for some reason, the docbuild will also fail.”)

[sagetrac-git]

Changed commit from 3bd5293 to 2bd8a8a

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

2bd8a8a

29231: fallback for scipy inventory file when not connected to internet

[mwageringel]

comment:5

You are right, that is a problem. It is possible to set a local inventory file as a fallback*. For Python, this was done by adding src/doc/common/python3.inv to the repository. However, I do not really like the idea of adding another binary file to the repository that would need to be updated manually.

Instead, I have configured intersphinx to use the python3.inv as fallback for Scipy. This means that cross-links for Scipy are not resolved when the fallback is used, as they are not present in the Python inventory file, but the documentation build still succeeds.

With these changes applied, I have successfully built the documentation without internet access.

---

*For reference, see Multiple target for the inventory.

[mwageringel]

Description changed:

--- 
+++ 
@@ -1,3 +1,5 @@
 This ticket adds an intersphinx mapping for Sphinx to resolve hyperlinks to the Scipy documentation.
 
-With this change, Sphinx fetches the Scipy inventory file `objects.inv` from https://docs.scipy.org/doc/scipy/reference/ during the docbuild. (If this fails for some reason, the docbuild will also fail.) It links against the latest version of the Scipy documentation to keep it simple.
+With this change, Sphinx fetches the Scipy inventory file `objects.inv` from https://docs.scipy.org/doc/scipy/reference/ during the docbuild. It links against the latest version of the Scipy documentation to keep it simple.
+
+If the download fails, for example when building Sage without internet access, the docbuild will still succeed, but the Scipy cross-links will not be resolved.