Skip to content
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.

Sign up for GitHub

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

Jump to bottom

link sphinx docs of Sage components in reference manual #27164

Closed
dimpase opened this issue Jan 29, 2019 · 10 comments · Fixed by #37575
Closed

link sphinx docs of Sage components in reference manual #27164

dimpase opened this issue Jan 29, 2019 · 10 comments · Fixed by #37575
Labels
c: documentation p: major / 3 t: bug
Milestone
sage-10.4

Comments

@dimpase
Copy link
Member

dimpase commented Jan 29, 2019

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
@dimpase dimpase added this to the sage-8.7 milestone Jan 29, 2019
@videlec
Copy link
Contributor

videlec commented Jan 29, 2019

comment:1

Question: how does this intersphinx will interplay with distribution installation (e.g. Gentoo, Archlinux, Debian, etc)?

@videlec

This comment has been minimized.

Sign in to view
@dimpase
Copy link
Member Author

dimpase commented Jan 29, 2019

comment:2

Replying to @videlec:

Question: how does this intersphinx will interplay with distribution installation (e.g. Gentoo, Archlinux, Debian, etc)?

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.

@timokau
Copy link
Contributor

timokau commented Jan 29, 2019

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?

@vinklein
Copy link
Mannequin

vinklein mannequin commented Jan 29, 2019

comment:4

Replying to @timokau:

I don't know much about intersphinx. Doesn't it simply link to online resources? Or does it also link offline docs together?

It can do both. When you declare a mapping let's say for numpy:

intersphinx_mapping = {'numpy': (URI, None)}

URI can be an online link or your numpy's documentation local directory.

@timokau
Copy link
Contributor

timokau commented Jan 29, 2019

comment:5

Well then as long as sage does The Right Thing with the URI, it shouldn't be an issue with packaging.

@embray
Copy link
Contributor

embray commented Mar 25, 2019

comment:6

Moving all blocker/critical issues from 8.7 to 8.8.

@embray embray modified the milestones: sage-8.7, sage-8.8 Mar 25, 2019
@embray
Copy link
Contributor

embray commented Jul 3, 2019

comment:7

Moving open critical and blocker issues to the next release milestone (optimistically).

@embray embray modified the milestones: sage-8.8, sage-8.9 Jul 3, 2019
@embray
Copy link
Contributor

embray commented Dec 30, 2019

comment:8

Ticket retargeted after milestone closed

@embray embray modified the milestones: sage-8.9, sage-9.1 Dec 30, 2019
@mkoeppe mkoeppe modified the milestones: sage-9.1, sage-9.2 May 5, 2020
@mkoeppe mkoeppe modified the milestones: sage-9.2, sage-9.3 Oct 24, 2020
@mkoeppe
Copy link
Contributor

mkoeppe commented Mar 24, 2021

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.

@mkoeppe mkoeppe modified the milestones: sage-9.3, sage-9.4 Mar 24, 2021
@mkoeppe mkoeppe modified the milestones: sage-9.4, sage-9.5 Jul 19, 2021
@mkoeppe mkoeppe modified the milestones: sage-9.5, sage-9.6 Dec 18, 2021
@mkoeppe mkoeppe modified the milestones: sage-9.6, sage-9.7 Apr 7, 2022
@mkoeppe mkoeppe modified the milestones: sage-9.7, sage-9.8 Aug 31, 2022
@mkoeppe mkoeppe removed this from the sage-9.8 milestone Jan 29, 2023
@nthiery nthiery mentioned this issue Jan 29, 2023
Open
vbraun pushed a commit to vbraun/sage that referenced this issue Mar 30, 2024
sagemathgh-37575: Intersphinx for cvxopt, cvxpy, cypari2, cysignals, …
6406386 
…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
@mkoeppe mkoeppe added this to the sage-10.4 milestone Mar 31, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
c: documentation p: major / 3 t: bug
Projects
None yet
Milestone
sage-10.4
5 participants
@embray @dimpase @timokau @videlec @mkoeppe