This came up in #29231 <https://trac.sagemath.org/ticket/29231>, and #27164 <https://trac.sagemath.org/ticket/27164> is related.
Several packages included with Sage use Sphinx for their documentation (such as numpy, scipy, sympy, matplotlib, pplpy, cypari, cysignals). For the quality of our documentation, it would be nice to have more cross-references to the online documentation of some of those projects. Sphinx supports this via the intersphinx extension <https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html>, which we already use for Python cross-references, for example, so that markup like :func:`map` is turned into a hyperlink to the corresponding Python documentation page. The way this works is that every Sphinx project provides an inventory file `objects.inv` containing mappings of objects that can be cross-referenced. Those inventory files are then inspected during our documentation build in order to resolve missing references. For Python and pplpy, the inventory files exist locally in Sage, which are the only ones used by Sage so far, but for other projects they can only be found online. Intersphinx can be configured to use local inventory files or to download them. It was brought up that building Sage should in principle work without an internet connection, so that downloading inventory files during the documentation build is suboptimal. At the same time, Sage is trying to move away from Sage-the-distribution, so that packaging third-party inventory files for offline use in Sage is undesirable as well, not to mention the maintenance overhead this would entail. This raises the question of how Sage should deal with these cross-references. My suggestion would be to do one of the following: 1. Allow the documentation build to trigger internet connections to download inventory files. If a download fails, we could either raise an error, or ignore it and just not resolve cross-links. The former is the approach that projects like numpy, scipy and matplotlib take. 2. Add a docbuild option to optionally enable downloading inventory files, similar to the `--no-plot` docbuild option for example. This way, the documentation would by default build without internet connection and without resolving cross-references to other projects. However, the option could be enabled for building the documentation files that are put on our website, which is presumably where most people read the Sage documentation. Comments and other suggestions are very welcome. Thanks. -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/sage-devel/e9ce9095-a07f-42d0-95c7-01f3ed16a740%40googlegroups.com.
