Reference manual: Show package list by category (math/front-end/other)

[mkoeppe]

Likewise, a selection of other packages is marked with a 'front-end' tag.

This tag is then used to break our long package lists in the documentation into math, front-end, and other packages, for better navigability:

https://deploy-preview-37315--sagemath.netlify.app/html/en/reference/spkg/

📝 Checklist

• The title is concise, informative, and self-explanatory.
• The description explains in detail what this PR is about.
• I have linked a relevant issue or discussion.
• I have created tests covering the changes.
• I have updated the documentation accordingly.

⌛ Dependencies

[videlec]

It indeed looks better in this one page of the sage documentation and might help a little for searches. Thanks!

Further questions not directly related to this specific MR but rather to package management that I am not sure where to post

• what is the way to install optional packages given that
  • sage -i is not an option for system sage (= not built from source)
  • some packages (such as bliss) require recompilation of some of the sage source code
  • sage -pip install is not an option on eg gentoo
• does/should sage provides some guarantee on these math packages such as
  • list compatibilities with sage versions
  • usage of sage coding practice in downstream packages

[videlec]

Though, about searches, I think that a random mathematician would rather google "how do I do X in sagemath" rather than looking at the documentation.

[mkoeppe]

Further questions not directly related to this specific MR but rather to package management that I am not sure where to post

• what is the way to install optional packages given that

  • sage -i is not an option for system sage (= not built from source)

Instead of pointing people to sage -i, point them to the SPKG page, which has the install instructions for all systems that carry the package. For example:
https://deploy-preview-37315--sagemath.netlify.app/html/en/reference/spkg/qepcad#equivalent-system-packages

Within the Sage library, you can write :ref:`qepcad <spkg_qepcad>`

• some packages (such as bliss) require recompilation of some of the sage source code

For that we now have the modularized distribution packages of the Sage library:

• https://deploy-preview-37315--sagemath.netlify.app/html/en/reference/spkg/sagemath_bliss#spkg-sagemath-bliss
• https://pypi.org/project/sagemath-bliss/

• sage -pip install is not an option on eg gentoo

Take a look at #37250

• does/should sage provides some guarantee on these math packages such as

  • list compatibilities with sage versions

Well, we test all optional packages in the Sage CI, for every Sage beta release.
For example: https://github.com/sagemath/sage/actions/runs/7604697685/job/20752529368

I look at these runs periodically, in particular in the rc phase.
That's how some of these notes come about:
https://github.com/sagemath/sage/wiki/Sage-10.2-Release-Tour#known-problems-and-workarounds

There's also #33338

• usage of sage coding practice in downstream packages

Soon to come with the modularization: That you can declare proper dependencies on parts of the Sage library (build-system requires, install-requires).
Take a look at #35095

[mkoeppe]

Though, about searches, I think that a random mathematician would rather google "how do I do X in sagemath" rather than looking at the documentation.

Sure. But they will also find outdated trash, something that worked ages ago or was hallucinated by an LLM.

In contrast to those old Sage wiki pages where the info on components and packages are collected, this documentation is generated from the same source as what is automatically tested.

[github-actions]

Documentation preview for this PR (built with commit 0f7aec6; changes) is ready! 🎉

[kcrisman]

What is yet to be reviewed here? Other than the proliferation of empty files, the documentation looks pretty good and is probably way better organized than our previous lists. But I feel like I'm missing something; did @videlec have a suggestion that you then implemented?

[mkoeppe]

All that is missing is someone giving the green light for merging it.

[kcrisman]

Okay. I have to admit the deploy preview thing is pretty nifty. Is there any mechanism to make sure the extra empty files are added if/when a new package shows up, other than the referee being aware of this new mechanism? Otherwise LGTM, and helps with organization to be sure.

[mkoeppe]

Well, these new tags are documented in the developer's guide, and the worst thing that can happen is that a math package is categorized as "other".

[kcrisman]

okay. Did I do this right under the new workflow?

[mkoeppe]

Perfect. Thank you!

[kcrisman]

you're welcome!

…

On Sat, Mar 2, 2024 at 7:54 PM Matthias Köppe ***@***.***> wrote: Perfect. Thank you! — Reply to this email directly, view it on GitHub <#37315 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AANRQ4G5VZTFNAESIU3N35TYWJYDTAVCNFSM6AAAAABDGAW56GVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSNZUHE3DEOJUHE> . You are receiving this because your review was requested.Message ID: ***@***.***>