Skip to content

Sphinx extlinks for ecl, gap, giac, maxima, meson, ppl, qepcad, scip, singular, soplex #37598

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

Merged
merged 8 commits into from
Mar 31, 2024
Merged

Sphinx extlinks for ecl, gap, giac, maxima, meson, ppl, qepcad, scip, singular, soplex #37598

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
7b0066a
src/sage/misc/sagedoc.py: Add extlinks for Giac, Maxima, Pari, PPL, S…
mkoeppe Mar 12, 2024
e10a725
src/doc/en/developer/sage_manuals.rst, src/sage/misc/sagedoc.py: Add …
mkoeppe Mar 16, 2024
eb5757c
src/doc/en/developer/sage_manuals.rst, src/sage/misc/sagedoc.py: Add …
mkoeppe Mar 17, 2024
5250624
src/doc/en/developer/sage_manuals.rst, src/sage/misc/sagedoc.py: Add …
mkoeppe Mar 17, 2024
2b9ba8a
src/sage/misc/sagedoc.py: Update gap manual URL
mkoeppe Mar 18, 2024
ca1d525
src/doc/en/developer/sage_manuals.rst, src/sage/misc/sagedoc.py: Upda…
mkoeppe Mar 20, 2024
bcb5c8a
Use :gap:, :gap_package: roles
mkoeppe Mar 20, 2024
13e15e9
Update src/sage/combinat/designs/incidence_structures.py
mkoeppe Mar 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 60 additions & 0 deletions src/doc/en/developer/sage_manuals.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -131,6 +131,66 @@ by Sage, you can link toward it without specifying its full path:
- ``:mathscinet:`MR0100971```
- :mathscinet:`MR0100971`

* - :ref:`ECL <spkg_ecl>`
- ``:ecl:`Manipulating-Lisp-objects```
- :ecl:`Manipulating-Lisp-objects`

* -
- ``:common_lisp:`RENAME-PACKAGE <f_rn_pkg>```
- :common_lisp:`RENAME-PACKAGE <f_rn_pkg>`

* - :ref:`GAP <spkg_gap>`
- ``:gap:`Groups <chap39>```
- :gap:`Groups <chap39>`

* -
- ``:gap_package:`guava```
- :gap_package:`guava`

* - :ref:`Giac <spkg_giac>`
- ``:giac_cascmd:`gbasis <node280>```
- :giac_cascmd:`gbasis <node280>`

* -
- ``:giac_us:`Unary-functions```
- :giac_us:`Unary-functions`

* - :ref:`Maxima <spkg_maxima>`
- ``:maxima:`struve_h <index-struve_005fh>```
- :maxima:`struve_h <index-struve_005fh>`

* - :ref:`Meson <spkg_meson>`
- ``:meson:`install_subdir <Reference-manual_functions.html#install_subdir>```
- :meson:`install_subdir <Reference-manual_functions.html#install_subdir>`

* - :ref:`Pari <spkg_pari>`
- ``:pari:`lfungenus2```
- :pari:`lfungenus2`

* - :ref:`polymake <spkg_polymake>`
- ``:polymake:`matroid```
- :polymake:`matroid`

* - :ref:`PPL <spkg_ppl>`
- ``:ppl:`Linear_Expression <classParma__Polyhedra__Library_1_1 Linear__Expression>```
- :ppl:`Linear_Expression <classParma__Polyhedra__Library_1_1Linear__Expression>`

* - :ref:`QEPCAD <spkg_qepcad>`
- ``:qepcad:`QEPCAD: Entering formulas <user/EnterForm>```
- :qepcad:`QEPCAD: Entering formulas <user/EnterForm>`

* - :ref:`SCIP <spkg_scip>`
- ``:scip:`SCIPsolve <group__PublicSolveMethods>```
- :scip:`SCIPsolve <group__PublicSolveMethods>`

* - :ref:`Singular <spkg_singular>`
- ``:singular:`stdfglm <sing_358>```
- :singular:`stdfglm <sing_358>`

* - :ref:`SoPlex <spkg_soplex>`
- ``:soplex:`soplex::LinSolverRational <classsoplex_1_1SLinSolverRational>```
- :soplex:`soplex::LinSolverRational <classsoplex_1_1SLinSolverRational>`

**http links:** copy/pasting a http link in the documentation works. If you want
a specific link name, use ```link name <http://www.example.com>`_``

Expand Down
16 changes: 15 additions & 1 deletion src/sage/misc/sagedoc.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -513,7 +513,21 @@ def process_dollars(s):
'oeis': ('https://oeis.org/%s', 'OEIS sequence %s'),
'doi': ('https://doi.org/%s', 'doi:%s'),
'pari': ('https://pari.math.u-bordeaux.fr/dochtml/help/%s', 'pari:%s'),
'mathscinet': ('https://www.ams.org/mathscinet-getitem?mr=%s', 'MathSciNet %s')
'mathscinet': ('https://www.ams.org/mathscinet-getitem?mr=%s', 'MathSciNet %s'),
'common_lisp': ('https://www.lispworks.com/documentation/lw50/CLHS/Body/%s.htm', 'Common Lisp: %s'),
'ecl': ('https://ecl.common-lisp.dev/static/manual/%s.html', 'ECL: %s'),
'gap': ('https://gap-system.org/Manuals/doc/ref/%s_mj.html', 'GAP: %s'),
'gap_package': ('https://www.gap-system.org/Packages/%s.html', 'GAP package %s'),
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just as heads-up, those URLs are probably not going to exist for much longer. Not sure what the goal here is, is it to link to the homepages of these packages? Or their documentation? Or what?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Anything really, I don't need anything very specific here for now. Package documentation would be fine.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@fingolfin What URL would you recommend to use for the package documentation?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@fingolfin And more generally (not for this PR) -- what would be the best way to link to specific functions or other objects in the GAP documentation in a stable way?
(For packages that use Sphinx to build their documentation, we use the cross-referencing tool Intersphinx for this purpose.)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While we still mirror the docs of distributed GAP packages on www.gap-system.org, the URLs there are not quite uniform, as the entry pages have different names / paths for each package.

This information is contained in the metadata of each package. That metadata is available in a JSON file (e.g. https://github.com/gap-system/gap/releases/download/v4.13.0/package-infos.json.gz for the packages distributed with GAP 4.13.0). I can provide further details if desired.

On the website we only link to the manual for the latest GAP release, and the manuals of the packages within that. So these are not really "stable".

I hope that we can eventually enhance this by adding version pickers. In preparation for this future (which may never come sigh but I am hoping), I made sure that from a certain point on, we had separate URLs for each GAP version -- these are not currently used anywhere! But as I wrote, I hope this will change.

The "regular" URLs for our mirrors of package manuals look like these (note the different paths after the package name)

The "versioned" ones look like this:

(So they are versioned by GAP version, not by package version. We could debate this at length, but let's not).

Anyway, so my suggestion would be to use these URLs.

But the annoying bit remains that you can't know the full URLs (.../doc/chap0.html or .../doc/chap0_mj.html or ..../htm/chapters.htm or maybe something else) without consulting that JSON file.

But perhaps we could just add a step to the script which updates the manuals on the GAP website for a new release, and add redirects ...

Since that script already is parsing the JSON data and more, it should be fairly easy to do. We use Apache, so the script could just produce a .htaccess file with suitable rules... (Actually it might be even easier to write a separate script which consumes a package-infos.json and spits out the .htaccess file; then it'd be very easy to apply it retroactively to prior GAP releases).

All that said, I am very busy with other stuff right now so I don't want to promise anything. If someone would like to help out, I can provide further details.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@fingolfin For example, might there be interest on your side in extending GAPDoc so it can output RST files and then go through Sphinx for the HTML build?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Those anchors are hashes and are essentially permanent. For our website we basically keep an index file (see https://github.com/gap-system/GapWWW/blob/master/_data/help.json which is exported from GAP via this script.)

Regarding "output RST files and then go through Sphinx for the HTML build": I am not really familiar with RST files and Sphinx. I am pretty sure I'd have a hard time convincing most GAP package maintainers to learn about those and installing relevant parts. But I guess it might still be potentially useful as an optional backend with added features (search, the ability to keep multiple versions and switch between them come to mind) that perhaps then is only used by the GAP website (and possibly via GH Action jobs also on package websites, if we can provide package authors with a "drop in and forget" solution).

As such, I would find that potentially interesting. To be fully useful, also the GAP help system would have to be taught to deal with the resulting HTML (GAP can be set up so that the REPL help opens the HTML docs at the correct position). I guess this is less important if it only is about producing online versions of those docs.

I have zero interest in working on that, but if someone else did, I'd be happy to try it out and give feedback.

I have no idea if there is any chance to get such a patch into GAPDoc, though (the maintainer sometimes has... strong oppinions). But it might not even be necessary, GAPDoc already has three "backends" ("plain text with escape sequences" for the REPL help; HTML; PDF-via-latex), and I think this is done in a way that makes it easy to add extra backends. So such a thing could perhaps be done via an extension package.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From the GAPDoc:

  # - add hash strings of the latter for links in HTML and PDF version
  #   (such that links remain stable as long as the (sub)section exists
  #   and stays in the same chapter)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess it might still be potentially useful as an optional backend with added features (search, the ability to keep multiple versions and switch between them come to mind) that perhaps then is only used by the GAP website (and possibly via GH Action jobs also on package websites, if we can provide package authors with a "drop in and forget" solution).

Yes, that's what I would imagine. No need to bring local building by GAP users/developers into the equation.

I have zero interest in working on that

Likewise, but that's a kind of project that would pretty easy to hire someone for. No math required!

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, I wish I could just hire someone for that kind of work, but in general this is very difficult with German university funding and general regulations on hiring people :/. Essentially I can hire local students (but good luck finding one with the skills). sigh

'giac_cascmd': ('https://www-fourier.ujf-grenoble.fr/~parisse/giac/doc/en/cascmd_en/%s.html', 'Giac: %s'),
'giac_us': ('https://www-fourier.ujf-grenoble.fr/~parisse/giac_us.html#%s', 'Giac API: %s'),
'maxima': ('https://maxima.sourceforge.io/docs/manual/maxima_singlepage.html#%s', 'Maxima: %s'),
'meson': ('https://mesonbuild.com/%s', 'Meson: %s'),
'polymake': ('https://polymake.org/doku.php/documentation/latest/%s', 'polymake: %s'),
'ppl': ('https://www.bugseng.com/products/ppl/documentation/user/ppl-user-1.2-html/%s.html', 'PPL: %s'),
'qepcad': ('https://www.usna.edu/CS/qepcadweb/B/%s.html', 'QEPCAD: %s'),
'scip': ('https://scipopt.org/doc/html/%s.php', 'SCIP: %s'),
'singular': ('https://www.singular.uni-kl.de/Manual/4-3-2/%s.htm', 'Singular: %s'),
'soplex': ('https://soplex.zib.de/doc/html/%s.php', 'SoPlex: %s'),
}


Expand Down