Skip to content

Commit 3e54eff

Browse files
author
Release Manager
committed
gh-35734: Reference manual: Show modularized sagelib packages separately <!-- Please provide a concise, informative and self-explanatory title. --> <!-- Don't put issue numbers in the title. Put it in the Description below. --> <!-- For example, instead of "Fixes #12345", use "Add a new method to multiply two integers" --> ### 📚 Description <!-- Describe your changes here in detail. --> Packages such as **sagemath-categories** are currently mixed with optional SPKGs in the reference guide. We separate them out as a separate category. We also move the section on `Feature`s right next to the package list. #35749 and follow-ups will interlink these sections. Preview: - https://deploy-preview-35734--sagemath- tobias.netlify.app/reference/spkg/index.html#packages-of-the- modularized-sage-library - https://deploy-preview-35734--sagemath- tobias.netlify.app/reference/spkg/index.html#runtime-detectable- features-and-conditional-doctests <!-- Why is this change required? What problem does it solve? --> <!-- If this PR resolves an open issue, please link to it here. For example "Fixes #12345". --> - Part of #29705 <!-- If your change requires a documentation PR, please link it appropriately. --> ### 📝 Checklist <!-- Put an `x` in all the boxes that apply. It should be `[x]` not `[x ]`. --> - [x] The title is concise, informative, and self-explanatory. - [x] 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 <!-- List all open PRs that this PR logically depends on - #12345: short description why this is a dependency - #34567: ... --> <!-- If you're unsure about any of these, don't hesitate to ask. We're here to help! --> URL: #35734 Reported by: Matthias Köppe Reviewer(s): Kwankyu Lee, Matthias Köppe
2 parents e0e8473 + 9f3a128 commit 3e54eff

34 files changed

+154
-124
lines changed

‎build/bin/sage-spkg-info

+1-1
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ PKG_SCRIPTS="$SAGE_ROOT/build/pkgs/$PKG_BASE"
99
for ext in rst txt; do
1010
SPKG_FILE="$PKG_SCRIPTS/SPKG.$ext"
1111
if [ -f "$SPKG_FILE" ]; then
12-
cat "$SPKG_FILE"
12+
sed "1,3s/^ *Sage: Open Source Mathematics Software:/$PKG_BASE:/" "$SPKG_FILE"
1313
break
1414
fi
1515
done

‎src/doc/bootstrap

+62-5
Original file line numberDiff line numberDiff line change
@@ -89,8 +89,8 @@ fi
8989
OUTPUT_INDEX="$OUTPUT_DIR"/index.rst
9090
cat > "$OUTPUT_INDEX" <<EOF
9191
92-
External Packages
93-
=================
92+
Packages and Features
93+
=====================
9494
9595
Standard Packages
9696
-----------------
@@ -100,7 +100,7 @@ Sage depends. It installs them automatically if it does not find
100100
equivalent system packages.
101101
102102
EOF
103-
for PKG_BASE in $(sage-package list --has-file SPKG.rst :standard: | sort); do
103+
for PKG_BASE in $(sage-package list --has-file SPKG.rst :standard: | grep -v '^sagemath_' | sort); do
104104
echo "* :ref:\`spkg_$PKG_BASE\`"
105105
done >> "$OUTPUT_INDEX"
106106
cat >> "$OUTPUT_INDEX" <<EOF
@@ -112,7 +112,55 @@ For additional functionality, you can install some of the following
112112
optional packages.
113113
114114
EOF
115-
for PKG_BASE in $(sage-package list --has-file SPKG.rst :optional: | sort); do
115+
for PKG_BASE in $(sage-package list --has-file SPKG.rst :optional: | grep -v '^sagemath_' | sort); do
116+
echo "* :ref:\`spkg_$PKG_BASE\`"
117+
done >> "$OUTPUT_INDEX"
118+
cat >> "$OUTPUT_INDEX" <<EOF
119+
120+
Features
121+
--------
122+
123+
.. toctree::
124+
:maxdepth: 1
125+
126+
sage/features
127+
sage/features/join_feature
128+
sage/features/all
129+
sage/features/sagemath
130+
sage/features/pkg_systems
131+
sage/features/bliss
132+
sage/features/csdp
133+
sage/features/databases
134+
sage/features/dvipng
135+
sage/features/ffmpeg
136+
sage/features/four_ti_2
137+
sage/features/gap
138+
sage/features/graph_generators
139+
sage/features/graphviz
140+
sage/features/imagemagick
141+
sage/features/interfaces
142+
sage/features/internet
143+
sage/features/kenzo
144+
sage/features/latex
145+
sage/features/latte
146+
sage/features/lrs
147+
sage/features/mcqd
148+
sage/features/meataxe
149+
sage/features/mip_backends
150+
sage/features/normaliz
151+
sage/features/pandoc
152+
sage/features/pdf2svg
153+
sage/features/polymake
154+
sage/features/rubiks
155+
sage/features/tdlib
156+
EOF
157+
cat >> "$OUTPUT_INDEX" <<EOF
158+
159+
Distribution Packages of the Sage Library
160+
-----------------------------------------
161+
162+
EOF
163+
for PKG_BASE in $(sage-package list --has-file SPKG.rst | grep '^sagemath_' | sort); do
116164
echo "* :ref:\`spkg_$PKG_BASE\`"
117165
done >> "$OUTPUT_INDEX"
118166
cat >> "$OUTPUT_INDEX" <<EOF
@@ -125,9 +173,10 @@ Some packages that provide additional functionality are marked as
125173
integration of these packages into the Sage distribution.
126174
127175
EOF
128-
for PKG_BASE in $(sage-package list --has-file SPKG.rst :experimental: | sort); do
176+
for PKG_BASE in $(sage-package list --has-file SPKG.rst :experimental: | grep -v '^sagemath_' | sort); do
129177
echo "* :ref:\`spkg_$PKG_BASE\`"
130178
done >> "$OUTPUT_INDEX"
179+
131180
cat >> "$OUTPUT_INDEX" <<EOF
132181
133182
All External Packages
@@ -142,11 +191,14 @@ EOF
142191

143192
OUTPUT_INDEX="$OUTPUT_DIR"/index_alph.rst
144193
cat >> "$OUTPUT_INDEX" <<EOF
194+
145195
Details of external packages
146196
============================
147197
148198
Packages are in alphabetical order.
149199
200+
.. default-role:: code
201+
150202
.. toctree::
151203
:maxdepth: 1
152204
@@ -160,3 +212,8 @@ for PKG_BASE in $(sage-package list --has-file SPKG.rst | sort); do
160212
(echo ".. _spkg_$PKG_BASE:" && echo && OUTPUT_RST=1 sage-spkg-info $PKG_BASE) | sed -e "s|https://github.com/sagemath/sage/issues/\([0-9]*\)|:issue:\`\1\`|g" -e "s|https://arxiv.org/abs/cs/\([0-9]*\)|:arxiv:\`cs/\1\`|g" > "$OUTPUT_DIR"/$PKG_BASE.rst
161213
echo >> "$OUTPUT_INDEX" " $PKG_BASE"
162214
done
215+
cat >> "$OUTPUT_INDEX" <<EOF
216+
217+
.. default-role::
218+
219+
EOF

‎src/doc/en/reference/misc/index.rst

-38
Original file line numberDiff line numberDiff line change
@@ -141,44 +141,6 @@ Fast Expression Evaluation
141141
.. sage/ext/interpreters/wrapper_rdf
142142
.. sage/ext/interpreters/wrapper_rr
143143
144-
Features
145-
~~~~~~~~
146-
147-
.. toctree::
148-
:maxdepth: 1
149-
150-
sage/features
151-
sage/features/join_feature
152-
sage/features/all
153-
sage/features/sagemath
154-
sage/features/pkg_systems
155-
sage/features/bliss
156-
sage/features/csdp
157-
sage/features/databases
158-
sage/features/dvipng
159-
sage/features/ffmpeg
160-
sage/features/four_ti_2
161-
sage/features/gap
162-
sage/features/graph_generators
163-
sage/features/graphviz
164-
sage/features/imagemagick
165-
sage/features/interfaces
166-
sage/features/internet
167-
sage/features/kenzo
168-
sage/features/latex
169-
sage/features/latte
170-
sage/features/lrs
171-
sage/features/mcqd
172-
sage/features/meataxe
173-
sage/features/mip_backends
174-
sage/features/normaliz
175-
sage/features/pandoc
176-
sage/features/pdf2svg
177-
sage/features/polymake
178-
sage/features/rubiks
179-
sage/features/tdlib
180-
181-
182144
Code Evaluation
183145
---------------
184146

‎src/sage/features/bliss.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@
3535

3636
class BlissLibrary(CythonFeature):
3737
r"""
38-
A :class:`~sage.features.Feature` which describes whether the Bliss library is
38+
A :class:`~sage.features.Feature` which describes whether the :ref:`Bliss library <spkg_bliss>` is
3939
present and functional.
4040
4141
EXAMPLES::

‎src/sage/features/cddlib.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717
class CddExecutable(Executable):
1818
r"""
1919
A :class:`~sage.features.Feature` describing the presence of an executable
20-
which comes as a part of ``cddlib``.
20+
which comes as a part of :ref:`cddlib <spkg_cddlib>`.
2121
2222
EXAMPLES::
2323

‎src/sage/features/csdp.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@
2525
class CSDP(Executable):
2626
r"""
2727
A :class:`~sage.features.Feature` which checks for the ``theta`` binary
28-
of CSDP.
28+
of :ref:`CSDP <spkg_csdp>`.
2929
3030
EXAMPLES::
3131

‎src/sage/features/databases.py

+20-12
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,8 @@
2626

2727
class DatabaseConwayPolynomials(StaticFile):
2828
r"""
29-
A :class:`~sage.features.Feature` which describes the presence of Frank Luebeck's
30-
database of Conway polynomials.
29+
A :class:`~sage.features.Feature` which describes the presence of :ref:`Frank Luebeck's
30+
database of Conway polynomials <spkg_conway_polynomials>`.
3131
3232
EXAMPLES::
3333
@@ -60,8 +60,8 @@ def __init__(self):
6060

6161
class DatabaseCremona(StaticFile):
6262
r"""
63-
A :class:`~sage.features.Feature` which describes the presence of John Cremona's
64-
database of elliptic curves.
63+
A :class:`~sage.features.Feature` which describes the presence of :ref:`John Cremona's
64+
database of elliptic curves <spkg_database_cremona_ellcurve>`.
6565
6666
INPUT:
6767
@@ -73,7 +73,7 @@ class DatabaseCremona(StaticFile):
7373
sage: from sage.features.databases import DatabaseCremona
7474
sage: DatabaseCremona('cremona_mini').is_present()
7575
FeatureTestResult('database_cremona_mini_ellcurve', True)
76-
sage: DatabaseCremona().is_present() # optional - database_cremona_ellcurve
76+
sage: DatabaseCremona().is_present() # optional - database_cremona_ellcurve
7777
FeatureTestResult('database_cremona_ellcurve', True)
7878
"""
7979
def __init__(self, name="cremona", spkg="database_cremona_ellcurve"):
@@ -94,7 +94,8 @@ def __init__(self, name="cremona", spkg="database_cremona_ellcurve"):
9494

9595
class DatabaseJones(StaticFile):
9696
r"""
97-
A :class:`~sage.features.Feature` which describes the presence of John Jones's tables of number fields.
97+
A :class:`~sage.features.Feature` which describes the presence of
98+
:ref:`John Jones's tables of number fields <spkg_database_jones_numfield>`.
9899
99100
EXAMPLES::
100101
@@ -118,12 +119,13 @@ def __init__(self):
118119

119120
class DatabaseKnotInfo(PythonModule):
120121
r"""
121-
A :class:`~sage.features.Feature` which describes the presence of the databases at the
122+
A :class:`~sage.features.Feature` which describes the presence of the
123+
:ref:`package providing the KnotInfo and LinkInfo databases <spkg_database_knotinfo>`.
124+
125+
The homes of these databases are the
122126
web-pages `KnotInfo <https://knotinfo.math.indiana.edu/>`__ and
123127
`LinkInfo <https://linkinfo.sitehost.iu.edu>`__.
124128
125-
126-
127129
EXAMPLES::
128130
129131
sage: from sage.features.databases import DatabaseKnotInfo
@@ -140,9 +142,13 @@ def __init__(self):
140142
"""
141143
PythonModule.__init__(self, 'database_knotinfo', spkg='database_knotinfo')
142144

145+
143146
class DatabaseCubicHecke(PythonModule):
144147
r"""
145-
A :class:`~sage.features.Feature` which describes the presence of the databases at the
148+
A :class:`~sage.features.Feature` which describes the presence of the
149+
:ref:`Cubic Hecke algebra database package <spkg_database_cubic_hecke>`.
150+
151+
The home of this database is the
146152
web-page `Cubic Hecke algebra on 4 strands <http://www.lamfa.u-picardie.fr/marin/representationH4-en.html>`__
147153
of Ivan Marin.
148154
@@ -162,10 +168,12 @@ def __init__(self):
162168
"""
163169
PythonModule.__init__(self, 'database_cubic_hecke', spkg='database_cubic_hecke')
164170

171+
165172
class DatabaseReflexivePolytopes(StaticFile):
166173
r"""
167-
A :class:`~sage.features.Feature` which describes the presence of the PALP database
168-
of reflexive lattice polytopes.
174+
A :class:`~sage.features.Feature` which describes the presence of the
175+
:ref:`PALP databases of reflexive three-dimensional <spkg_polytopes_db>`
176+
and :ref:`four-dimensional lattice polytopes <spkg_polytopes_db_4d>`.
169177
170178
EXAMPLES::
171179

‎src/sage/features/ffmpeg.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515

1616
class FFmpeg(Executable):
1717
r"""
18-
A :class:`~sage.features.Feature` describing the presence of ``ffmpeg``
18+
A :class:`~sage.features.Feature` describing the presence of :ref:`ffmpeg <spkg_ffmpeg>`.
1919
2020
EXAMPLES::
2121

‎src/sage/features/four_ti_2.py

+2-2
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88

99
class FourTi2Executable(Executable):
1010
r"""
11-
A :class:`~sage.features.Feature` for the 4ti2 executables.
11+
A :class:`~sage.features.Feature` for the :ref:`4ti2 <spkg_4ti2>` executables.
1212
"""
1313
def __init__(self, name):
1414
r"""
@@ -27,7 +27,7 @@ def __init__(self, name):
2727

2828
class FourTi2(JoinFeature):
2929
r"""
30-
A :class:`~sage.features.Feature` describing the presence of the ``4ti2`` executables.
30+
A :class:`~sage.features.Feature` describing the presence of all :ref:`4ti2 <spkg_4ti2>` executables.
3131
3232
EXAMPLES::
3333

‎src/sage/features/gap.py

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
r"""
2-
Features for testing the presence of GAP packages
2+
Features for testing the presence of the SageMath interfaces to ``gap`` and of GAP packages
33
"""
44
# *****************************************************************************
55
# Copyright (C) 2016 Julian Rüth
@@ -62,7 +62,7 @@ def _is_present(self):
6262
class sage__libs__gap(JoinFeature):
6363
r"""
6464
A :class:`sage.features.Feature` describing the presence of :mod:`sage.libs.gap`
65-
(the library interface to GAP) and :mod:`sage.interfaces.gap` (the pexpect
65+
(the library interface to :ref:`GAP <spkg_gap>`) and :mod:`sage.interfaces.gap` (the pexpect
6666
interface to GAP). By design, we do not distinguish between these two, in order
6767
to facilitate the conversion of code from the pexpect interface to the library
6868
interface.

‎src/sage/features/gfan.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616

1717
class GfanExecutable(Executable):
1818
r"""
19-
A :class:`~sage.features.Feature` for the gfan executables.
19+
A :class:`~sage.features.Feature` for the :ref:`gfan <spkg_gfan>` executables.
2020
"""
2121
def __init__(self, cmd=None):
2222
r"""

‎src/sage/features/graph_generators.py

+4-4
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
r"""
2-
Features for testing the presence of various graph generator programs
2+
Features for testing the presence of graph generator programs ``benzene``, ``buckygen``, ``plantri``
33
"""
44

55
# *****************************************************************************
@@ -23,7 +23,7 @@
2323

2424
class Plantri(Executable):
2525
r"""
26-
A :class:`~sage.features.Feature` which checks for the ``plantri`` binary.
26+
A :class:`~sage.features.Feature` which checks for the :ref:`plantri <spkg_plantri>` binary.
2727
2828
EXAMPLES::
2929
@@ -70,7 +70,7 @@ def is_functional(self):
7070

7171
class Buckygen(Executable):
7272
r"""
73-
A :class:`~sage.features.Feature` which checks for the ``buckygen`` binary.
73+
A :class:`~sage.features.Feature` which checks for the :ref:`buckygen <spkg_buckygen>` binary.
7474
7575
EXAMPLES::
7676
@@ -117,7 +117,7 @@ def is_functional(self):
117117

118118
class Benzene(Executable):
119119
r"""
120-
A :class:`~sage.features.Feature` which checks for the ``benzene``
120+
A :class:`~sage.features.Feature` which checks for the :ref:`benzene <spkg_benzene>`
121121
binary.
122122
123123
EXAMPLES::

0 commit comments

Comments
 (0)