-
-
Notifications
You must be signed in to change notification settings - Fork 491
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
link sphinx docs of Sage components in reference manual #27164
Comments
comment:1
Question: how does this intersphinx will interplay with distribution installation (e.g. Gentoo, Archlinux, Debian, etc)? |
This comment has been minimized.
This comment has been minimized.
comment:2
Replying to @videlec:
This is a question for packagers. I have no idea what they do with Sage's docs. I cc'd the packagers I can think of. |
comment:3
I don't know much about intersphinx. Doesn't it simply link to online resources? Or does it also link offline docs together? |
comment:4
Replying to @timokau:
It can do both. When you declare a mapping let's say for numpy:
|
comment:5
Well then as long as sage does The Right Thing with the URI, it shouldn't be an issue with packaging. |
comment:6
Moving all blocker/critical issues from 8.7 to 8.8. |
comment:7
Moving open critical and blocker issues to the next release milestone (optimistically). |
comment:8
Ticket retargeted after milestone closed |
comment:11
Sage development has entered the release candidate phase for 9.3. Setting a new milestone for this ticket based on a cursory review of ticket status, priority, and last modification date. |
…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
As Sage gets increasingly modular, it becomes important (also for the doc website, currently it has broken links to e.g. sagenb interacts in the reference manual) that these spun off docs are still easy to find.
In fact, sphinx has an extension to link different projects,
see http://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
so this appears quite doable.
Here is an incomplete docs to link
CC: @embray @kiwifb @antonio-rojas @timokau @infinity0
Component: documentation
Issue created by migration from https://trac.sagemath.org/ticket/27164
The text was updated successfully, but these errors were encountered: