Package breathe - Sphinx plugin for project documentation using Doxygen
#37577
Labels
Comments
vbraun
pushed a commit
to vbraun/sage
that referenced
this issue
Mar 30, 2024
…flint, fpylll, gmpy2, ipywidgets, matplotlib, mpmath, networkx, numpy, rpy2, scipy, sympy
<!-- ^ Please provide a concise and informative title. -->
<!-- ^ Don't put issue numbers in the title, do this in the PR
description below. -->
<!-- ^ For example, instead of "Fixes sagemath#12345" use "Introduce new method
to calculate 1 + 2". -->
<!-- v Describe your changes below in detail. -->
<!-- v Why is this change required? What problem does it solve? -->
<!-- v If this PR resolves an open issue, please link to it here. For
example, "Fixes sagemath#12345". -->
[Intersphinx](https://www.sphinx-
doc.org/en/master/usage/extensions/intersphinx.html) allows us to refer
to functions and classes in other projects using the standard Sphinx
roles `:func:`, `:class:`, ...
Examples in the documentation preview:
- [References to FLINT functions in
sage.libs.flint.arith_sage](https://deploy-preview-37575--sagemath.netli
fy.app/html/en/reference/libs/sage/libs/flint/arith_sage#sage.libs.flint
.arith_sage.bell_number)
- [References to SciPy functions in
sage.manifolds.differentiable.integrated_curve](https://deploy-
preview-37575--sagemath.netlify.app/html/en/reference/manifolds/sage/man
ifolds/differentiable/integrated_curve#sage.manifolds.differentiable.int
egrated_curve.IntegratedCurve.solve)
- [References to NetworkX functions in
sage.graphs.generic_graph](https://deploy-preview-37575--sagemath.netlif
y.app/html/en/reference/graphs/sage/graphs/generic_graph#sage.graphs.gen
eric_graph.GenericGraph.export_to_file)
- [Examples in the Developer Guide](https://deploy-preview-37575--
sagemath.netlify.app/html/en/developer/sage_manuals#hyperlinks)
Based on a rebased version of sagemath#29231 by @mwageringel. In addition to the
`scipy` intersphinx done in sagemath#29231, here we add a number of relevant
Python libraries, as well as `flint`, whose docs are built with Sphinx
as well.
To address concerns in the discussion there about the docbuild
contacting remote servers for the inventory files, here we instead
vendor the inventory files:
```
$ ls -l src/doc/common/_vendor
-rw-r--r-- 1 mkoeppe staff 1942 Mar 9 21:20 cvxopt.inv
-rw-r--r-- 1 mkoeppe staff 13251 Mar 9 21:20 cvxpy.inv
-rw-r--r-- 1 mkoeppe staff 10728 Mar 9 21:20 cypari2.inv
-rw-r--r-- 1 mkoeppe staff 775 Mar 9 21:20 cysignals.inv
-rw-r--r-- 1 mkoeppe staff 246266 Mar 9 21:20 flint.inv
-rw-r--r-- 1 mkoeppe staff 1603 Mar 9 21:20 fpylll.inv
-rw-r--r-- 1 mkoeppe staff 2891 Mar 9 21:20 gmpy2.inv
-rw-r--r-- 1 mkoeppe staff 10934 Mar 9 21:20 ipywidgets.inv
-rw-r--r-- 1 mkoeppe staff 105887 Mar 9 21:20 matplotlib.inv
-rw-r--r-- 1 mkoeppe staff 3115 Mar 9 21:20 mpmath.inv
-rw-r--r-- 1 mkoeppe staff 51830 Mar 9 21:20 networkx.inv
-rw-r--r-- 1 mkoeppe staff 78006 Mar 9 21:20 numpy.inv
-rw-r--r-- 1 mkoeppe staff 1449 Mar 9 21:20 pplpy.inv
-rw-r--r-- 1 mkoeppe staff 136166 Mar 9 21:20 python.inv
-rw-r--r-- 1 mkoeppe staff 3289 Mar 9 21:20 rpy2.inv
-rw-r--r-- 1 mkoeppe staff 112691 Mar 9 21:20 scipy.inv
-rw-r--r-- 1 mkoeppe staff 55596 Mar 9 21:20 sympy.inv
```
This extends our existing practice with the Python inventory (moved here
from its previous location `src/doc/common/python3.inv`). The new
command `sage -python -m sage_docbuild.vendor` retrieves the latest
versions of these files. (Distribution notes: These files are not
installed, as they are only needed at the build time of the
documentation. After sagemath#36730, they are part of the sdist of sagemath-doc-
html, but not part of the wheel.)
By setting `SAGE_DOC_REMOTE_INVENTORIES=yes`, this can be overridden, as
previously suggested in
sagemath#29231 (comment).
In this case it is first tried to contact the remote servers.
Fixes sagemath#29231 (stalled since 2020).
Fixes sagemath#27164 (stalled since 2019).
**Outside the scope of this PR:**
- adding such Intersphinx links everywhere (that would be a long-term
writing project - https://groups.google.com/g/sage-
devel/c/PfYpuOWt8xQ/m/Emn7pZd5AQAJ)
- linking to documentation of non-Sphinx projects (see sagemath#37598, sagemath#37577)
- any considerations how these .inv files could/should/would be taken
from our installations of these packages, or from system packages that
ship the documentation.
### 📝 Checklist
<!-- Put an `x` in all the boxes that apply. -->
- [x] The title is concise and informative.
- [ ] The description explains in detail what this PR is about.
- [x] I have linked a relevant issue or discussion.
- [ ] I have created tests covering the changes.
- [ ] I have updated the documentation accordingly.
### ⌛ Dependencies
<!-- List all open PRs that this PR logically depends on. For example,
-->
<!-- - sagemath#12345: short description why this is a dependency -->
<!-- - sagemath#34567: ... -->
URL: sagemath#37575
Reported by: Matthias Köppe
Reviewer(s): David Coudert, Matthias Köppe
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/
Alternatives: https://github.com/boschglobal/doxysphinx/blob/main/docs/alternatives.md
The text was updated successfully, but these errors were encountered: