Skip to content

Commit 6cb86d9

Browse files
author
Release Manager
committed
gh-37056: Installation guide: Show system package commands using sphinx-inline-tabs <!-- ^^^^^ Please provide a concise, informative and self-explanatory title. Don't put issue numbers in there, do this in the PR body below. For example, instead of "Fixes #1234" use "Introduce new method to calculate 1+1" --> <!-- Describe your changes here in detail --> Preview: https://deploy-preview-37056-- sagemath.netlify.app/html/en/installation/source#linux-system-package- installation Same for the SPKG pages in the reference manual. https://deploy- preview-37056-- sagemath.netlify.app/html/en/reference/spkg/gfortran#equivalent-system- packages Same for the git instructions in the developer guide, using 2 tabs for HTTPS and SSH: https://deploy-preview-37056-- sagemath.netlify.app/html/en/developer/github#forking-the-sage- repository <!-- 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". --> <!-- If your change requires a documentation PR, please link it appropriately. --> ### 📝 Checklist <!-- Put an `x` in all the boxes that apply. --> <!-- If your change requires a documentation PR, please link it appropriately --> <!-- If you're unsure about any of these, don't hesitate to ask. We're here to help! --> <!-- Feel free to remove irrelevant items. --> - [x] 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 <!-- List all open PRs that this PR logically depends on - #12345: short description why this is a dependency - #34567: ... --> - Depends on #36957 (merged here) <!-- If you're unsure about any of these, don't hesitate to ask. We're here to help! --> URL: #37056 Reported by: Matthias Köppe Reviewer(s): Kwankyu Lee
2 parents eb9d9d0 + 2392b19 commit 6cb86d9

File tree

15 files changed

+191
-156
lines changed

15 files changed

+191
-156
lines changed

‎build/bin/sage-print-system-package-command

+5-2
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ SUDO=
77
PROMPT=
88
SPKG=no
99
if [ -n "$OUTPUT_RST" ]; then
10-
COMMENT=""
10+
COMMENT="$RST_INDENT"
1111
else
1212
COMMENT="# "
1313
fi
@@ -86,7 +86,7 @@ function print_shell_command()
8686
{
8787
if [ -n "$OUTPUT_RST" ]; then
8888
echo
89-
echo ".. CODE-BLOCK:: bash"
89+
echo "$RST_INDENT.. CODE-BLOCK:: bash"
9090
echo
9191
fi
9292
# shell-quote arguments if necessary
@@ -103,6 +103,9 @@ function print_shell_command()
103103

104104
function print_comment()
105105
{
106+
if [ -n "$OUTPUT_RST" ]; then
107+
echo
108+
fi
106109
echo "${COMMENT}$1"
107110
}
108111

‎build/bin/sage-spkg-info

+38-18
Original file line numberDiff line numberDiff line change
@@ -12,12 +12,16 @@ if [ -n "$OUTPUT_RST" ]; then
1212
echo ".. _spkg_$PKG_BASE:"
1313
echo
1414
ref () { echo ":ref:\`$1\`"; }
15+
spkg () { ref spkg_$1; }
1516
issue () { echo ":issue:\`$1\`"; }
1617
code () { echo "\`\`$*\`\`"; }
18+
tab () { echo ".. tab:: $1"; }
1719
else
1820
ref () { echo "$1"; }
21+
spkg () { echo "$1"; }
1922
issue () { echo "https://github.com/sagemath/sage/issues/$1"; }
2023
code () { echo "$1"; }
24+
tab () { echo "$1:"; }
2125
fi
2226
PKG_SCRIPTS="$SAGE_ROOT/build/pkgs/$PKG_BASE"
2327
for ext in rst txt; do
@@ -56,7 +60,7 @@ for dep_file in dependencies dependencies_order_only; do
5660
# Looks like a package
5761
*) if [ -r "$SAGE_ROOT/build/pkgs/$dep/SPKG.rst" ]; then
5862
# This RST label is set in src/doc/bootstrap
59-
echo "- $(ref spkg_$dep)"
63+
echo "- $(spkg $dep)"
6064
else
6165
echo "- $dep"
6266
fi;;
@@ -96,31 +100,47 @@ for system_package_file in "$PKG_DISTROS"/*.txt; do
96100
esac
97101
fi
98102
done
99-
if [ $have_repology = yes ]; then
100-
systems="$systems repology"
101-
fi
102103
system=
104+
# Show using inline tabs
105+
export RST_INDENT=" "
103106
for system in $systems; do
104107
system_package_file="$PKG_DISTROS"/$system.txt
105108
system_packages="$(echo $(sed 's/#.*//;' $system_package_file))"
106109
case $system in
107-
debian)
108-
# Generic
109-
echo "Debian/Ubuntu:"
110-
;;
111-
fedora)
112-
# Generic
113-
echo "Fedora/Redhat/CentOS:"
114-
;;
115-
repology)
116-
;;
117-
*)
118-
echo "$system:"
119-
;;
110+
alpine) tab "Alpine";;
111+
arch) tab "Arch Linux";;
112+
conda) tab "conda-forge";;
113+
cygwin) tab "Cygwin";;
114+
debian) tab "Debian/Ubuntu";;
115+
fedora) tab "Fedora/Redhat/CentOS";;
116+
freebsd) tab "FreeBSD";;
117+
gentoo) tab "Gentoo Linux";;
118+
homebrew) tab "Homebrew";;
119+
macports) tab "MacPorts";;
120+
nix) tab "Nixpkgs";;
121+
openbsd) tab "OpenBSD";;
122+
opensuse) tab "openSUSE";;
123+
slackware) tab "Slackware";;
124+
void) tab "Void Linux";;
125+
repology) ;;
126+
*) tab "$system";;
120127
esac
121-
sage-print-system-package-command $system --wrap --prompt=' $ ' --continuation=' ' --sudo install $system_packages
128+
if [ -n "$system_packages" ]; then
129+
sage-print-system-package-command $system --wrap --prompt="$RST_INDENT"' $ ' --continuation="$RST_INDENT"' ' --sudo install $system_packages
130+
else
131+
echo
132+
echo "${RST_INDENT}No package needed."
133+
fi
122134
echo
123135
done
136+
unset RST_INDENT
137+
if [ $have_repology = yes ]; then
138+
# Show below the inline tabs
139+
system=repology
140+
system_package_file="$PKG_DISTROS"/$system.txt
141+
system_packages="$(echo $(sed 's/#.*//;' $system_package_file))"
142+
sage-print-system-package-command $system --wrap --prompt=' $ ' --continuation=' ' --sudo install $system_packages
143+
fi
124144
if [ -z "$system" ]; then
125145
echo "(none known)"
126146
else

‎build/pkgs/calver/distros/package-version.txt

-1
This file was deleted.

‎build/pkgs/sagemath_doc_html/dependencies

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
sagelib sphinx sphinx_copybutton pplpy_doc | $(SAGERUNTIME) maxima networkx scipy sympy matplotlib pillow mathjax mpmath ipykernel jupyter_client conway_polynomials tachyon jmol ipywidgets jupyter_sphinx sage_docbuild elliptic_curves furo fpylll
1+
sagelib sphinx sphinx_copybutton sphinx_inline_tabs pplpy_doc | $(SAGERUNTIME) maxima networkx scipy sympy matplotlib pillow mathjax mpmath ipykernel jupyter_client conway_polynomials tachyon jmol ipywidgets jupyter_sphinx sage_docbuild elliptic_curves furo fpylll
22

33
# Building the documentation has many dependencies, because all
44
# documented modules are imported and because we use matplotlib to

‎build/pkgs/sphinx_inline_tabs/SPKG.rst

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
sphinx_inline_tabs: Add inline tabbed content to your Sphinx documentation.
2+
===========================================================================
3+
4+
Description
5+
-----------
6+
7+
Add inline tabbed content to your Sphinx documentation.
8+
9+
License
10+
-------
11+
12+
Upstream Contact
13+
----------------
14+
15+
https://pypi.org/project/sphinx-inline-tabs/
16+

‎build/pkgs/sphinx_inline_tabs/checksums.ini

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
tarball=sphinx_inline_tabs-VERSION-py3-none-any.whl
2+
sha1=1404e320d0533280355e7e1e71cffd9937015027
3+
md5=7373d0ebd34be8f9ac2ed62bc63f4582
4+
cksum=2708358042
5+
upstream_url=https://pypi.io/packages/py3/s/sphinx_inline_tabs/sphinx_inline_tabs-VERSION-py3-none-any.whl

‎build/pkgs/sphinx_inline_tabs/dependencies

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
sphinx | $(PYTHON_TOOLCHAIN) $(PYTHON)
2+
3+
----------
4+
All lines of this file are ignored except the first.

‎build/pkgs/sphinx_inline_tabs/install-requires.txt

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
sphinx-inline-tabs

‎build/pkgs/sphinx_inline_tabs/package-version.txt

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
2023.4.21

‎build/pkgs/sphinx_inline_tabs/spkg-configure.m4

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
SAGE_SPKG_CONFIGURE([sphinx_inline_tabs], [
2+
SAGE_PYTHON_PACKAGE_CHECK([sphinx_inline_tabs])
3+
])

‎build/pkgs/sphinx_inline_tabs/type

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
standard

‎configure.ac

+1-1
Original file line numberDiff line numberDiff line change
@@ -523,7 +523,7 @@ AC_ARG_ENABLE([doc],
523523
AS_HELP_STRING([--disable-doc],
524524
[disable build of the Sage documentation and packages depending on it]), [
525525
dnl Disable packages needed for docbuilding
526-
for pkg in sage_docbuild alabaster babel snowballstemmer imagesize sphinx sphinxcontrib_devhelp sphinxcontrib_jsmath sphinxcontrib_serializinghtml sphinxcontrib_applehelp sphinxcontrib_htmlhelp sphinxcontrib_qthelp sphinxcontrib_websupport jupyter_sphinx furo sphinx_copybutton mathjax sphinx_basic_ng; do
526+
for pkg in sage_docbuild alabaster babel snowballstemmer imagesize sphinx sphinxcontrib_devhelp sphinxcontrib_jsmath sphinxcontrib_serializinghtml sphinxcontrib_applehelp sphinxcontrib_htmlhelp sphinxcontrib_qthelp sphinxcontrib_websupport jupyter_sphinx furo sphinx_copybutton sphinx_inline_tabs mathjax sphinx_basic_ng; do
527527
AS_VAR_SET([SAGE_ENABLE_$pkg], [$enableval])
528528
done
529529
AS_VAR_IF([enableval], [no], [dnl Disable the docbuild by disabling the install tree for documentation

‎src/doc/en/developer/github.rst

+60-14
Original file line numberDiff line numberDiff line change
@@ -123,7 +123,11 @@ https://github.com/alice/sage.
123123

124124
Next if you don't have a local Git repo of Sage, then start afresh `cloning
125125
your fork
126-
<https://docs.github.com/en/get-started/quickstart/fork-a-repo#cloning-your-forked-repository>`_::
126+
<https://docs.github.com/en/get-started/quickstart/fork-a-repo#cloning-your-forked-repository>`_:
127+
128+
.. tab:: By HTTPS protocol
129+
130+
::
127131

128132
[alice@localhost ~]$ git clone https://github.com/alice/sage.git
129133
Cloning into 'sage'...
@@ -139,7 +143,30 @@ your fork
139143
origin https://github.com/alice/sage.git (fetch)
140144
origin https://github.com/alice/sage.git (push)
141145

142-
If you already have a local Git repo and only want to link your fork as ``origin`` remote, then do::
146+
.. tab:: By SSH protocol
147+
148+
::
149+
150+
[alice@localhost ~]$ git clone [email protected]:alice/sage.git
151+
Cloning into 'sage'...
152+
remote: Enumerating objects: 914565, done.
153+
remote: Counting objects: 100% (2738/2738), done.
154+
remote: Compressing objects: 100% (855/855), done.
155+
remote: Total 914565 (delta 1950), reused 2493 (delta 1875), pack-reused 911827
156+
Receiving objects: 100% (914565/914565), 331.09 MiB | 11.22 MiB/s, done.
157+
Resolving deltas: 100% (725438/725438), done.
158+
Updating files: 100% (9936/9936), done.
159+
[alice@localhost ~]$ cd sage
160+
[alice@localhost sage]$ git remote -v
161+
origin [email protected]:alice/sage.git (fetch)
162+
origin [email protected]:alice/sage.git (push)
163+
164+
165+
If you already have a local Git repo and only want to link your fork as ``origin`` remote, then do:
166+
167+
.. tab:: By HTTPS protocol
168+
169+
::
143170

144171
[alice@localhost sage]$ git remote add origin https://github.com/alice/sage.git
145172
[alice@localhost sage]$ git remote -v
@@ -155,7 +182,29 @@ If you already have a local Git repo and only want to link your fork as ``origin
155182
From https://github.com/alice/sage
156183
* [new branch] develop -> origin/develop
157184

158-
You also add the Sage repo ``sagemath/sage`` as your remote ``upstream``::
185+
.. tab:: By SSH protocol
186+
187+
::
188+
189+
[alice@localhost sage]$ git remote add origin [email protected]:alice/sage.git
190+
[alice@localhost sage]$ git remote -v
191+
origin [email protected]:alice/sage.git (fetch)
192+
origin [email protected]:alice/sage.git (push)
193+
[alice@localhost sage]$ git fetch origin
194+
remote: Enumerating objects: 1136, done.
195+
remote: Counting objects: 100% (1084/1084), done.
196+
remote: Compressing objects: 100% (308/308), done.
197+
remote: Total 1136 (delta 825), reused 982 (delta 776), pack-reused 52
198+
Receiving objects: 100% (1136/1136), 2.62 MiB | 5.30 MiB/s, done.
199+
Resolving deltas: 100% (838/838), completed with 145 local objects.
200+
From [email protected]:alice/sage
201+
* [new branch] develop -> origin/develop
202+
203+
You also add the Sage repo ``sagemath/sage`` as your remote ``upstream``:
204+
205+
.. tab:: By HTTPS protocol
206+
207+
::
159208

160209
[alice@localhost sage]$ git remote add upstream https://github.com/sagemath/sage.git
161210
[alice@localhost sage]$ git remote -v
@@ -164,19 +213,16 @@ You also add the Sage repo ``sagemath/sage`` as your remote ``upstream``::
164213
upstream https://github.com/sagemath/sage.git (fetch)
165214
upstream https://github.com/sagemath/sage.git (push)
166215

216+
.. tab:: By SSH protocol
167217

168-
.. NOTE::
169-
170-
If you linked your Git to GitHub by SSH protocol, then do the following
171-
instead to set up remotes::
218+
::
172219

173-
[alice@localhost sage]$ git remote add origin [email protected]:alice/sage.git
174-
[alice@localhost sage]$ git remote add upstream [email protected]:sagemath/sage.git
175-
[alice@localhost sage]$ git remote -v
176-
origin [email protected]:alice/sage.git (fetch)
177-
origin [email protected]:alice/sage.git (push)
178-
upstream [email protected]:sagemath/sage.git (fetch)
179-
upstream [email protected]:sagemath/sage.git (push)
220+
[alice@localhost sage]$ git remote add upstream [email protected]:sagemath/sage.git
221+
[alice@localhost sage]$ git remote -v
222+
origin [email protected]:alice/sage.git (fetch)
223+
origin [email protected]:alice/sage.git (push)
224+
upstream [email protected]:sagemath/sage.git (fetch)
225+
upstream [email protected]:sagemath/sage.git (push)
180226

181227
To prevent accidental pushes to ``upstream`` (instead of ``origin``), you may want to disable it by running::
182228

0 commit comments

Comments
 (0)