diff --git a/build/bin/sage-print-system-package-command b/build/bin/sage-print-system-package-command index 722a7f75161..daf61c48c09 100755 --- a/build/bin/sage-print-system-package-command +++ b/build/bin/sage-print-system-package-command @@ -7,7 +7,7 @@ SUDO= PROMPT= SPKG=no if [ -n "$OUTPUT_RST" ]; then - COMMENT="" + COMMENT="$RST_INDENT" else COMMENT="# " fi @@ -86,7 +86,7 @@ function print_shell_command() { if [ -n "$OUTPUT_RST" ]; then echo - echo ".. CODE-BLOCK:: bash" + echo "$RST_INDENT.. CODE-BLOCK:: bash" echo fi # shell-quote arguments if necessary @@ -103,6 +103,9 @@ function print_shell_command() function print_comment() { + if [ -n "$OUTPUT_RST" ]; then + echo + fi echo "${COMMENT}$1" } diff --git a/build/bin/sage-spkg-info b/build/bin/sage-spkg-info index 6b66e584331..b7b91a63339 100755 --- a/build/bin/sage-spkg-info +++ b/build/bin/sage-spkg-info @@ -12,12 +12,16 @@ if [ -n "$OUTPUT_RST" ]; then echo ".. _spkg_$PKG_BASE:" echo ref () { echo ":ref:\`$1\`"; } + spkg () { ref spkg_$1; } issue () { echo ":issue:\`$1\`"; } code () { echo "\`\`$*\`\`"; } + tab () { echo ".. tab:: $1"; } else ref () { echo "$1"; } + spkg () { echo "$1"; } issue () { echo "https://github.com/sagemath/sage/issues/$1"; } code () { echo "$1"; } + tab () { echo "$1:"; } fi PKG_SCRIPTS="$SAGE_ROOT/build/pkgs/$PKG_BASE" for ext in rst txt; do @@ -56,7 +60,7 @@ for dep_file in dependencies dependencies_order_only; do # Looks like a package *) if [ -r "$SAGE_ROOT/build/pkgs/$dep/SPKG.rst" ]; then # This RST label is set in src/doc/bootstrap - echo "- $(ref spkg_$dep)" + echo "- $(spkg $dep)" else echo "- $dep" fi;; @@ -96,31 +100,47 @@ for system_package_file in "$PKG_DISTROS"/*.txt; do esac fi done -if [ $have_repology = yes ]; then - systems="$systems repology" -fi system= +# Show using inline tabs +export RST_INDENT=" " for system in $systems; do system_package_file="$PKG_DISTROS"/$system.txt system_packages="$(echo $(sed 's/#.*//;' $system_package_file))" case $system in - debian) - # Generic - echo "Debian/Ubuntu:" - ;; - fedora) - # Generic - echo "Fedora/Redhat/CentOS:" - ;; - repology) - ;; - *) - echo "$system:" - ;; + alpine) tab "Alpine";; + arch) tab "Arch Linux";; + conda) tab "conda-forge";; + cygwin) tab "Cygwin";; + debian) tab "Debian/Ubuntu";; + fedora) tab "Fedora/Redhat/CentOS";; + freebsd) tab "FreeBSD";; + gentoo) tab "Gentoo Linux";; + homebrew) tab "Homebrew";; + macports) tab "MacPorts";; + nix) tab "Nixpkgs";; + openbsd) tab "OpenBSD";; + opensuse) tab "openSUSE";; + slackware) tab "Slackware";; + void) tab "Void Linux";; + repology) ;; + *) tab "$system";; esac - sage-print-system-package-command $system --wrap --prompt=' $ ' --continuation=' ' --sudo install $system_packages + if [ -n "$system_packages" ]; then + sage-print-system-package-command $system --wrap --prompt="$RST_INDENT"' $ ' --continuation="$RST_INDENT"' ' --sudo install $system_packages + else + echo + echo "${RST_INDENT}No package needed." + fi echo done +unset RST_INDENT +if [ $have_repology = yes ]; then + # Show below the inline tabs + system=repology + system_package_file="$PKG_DISTROS"/$system.txt + system_packages="$(echo $(sed 's/#.*//;' $system_package_file))" + sage-print-system-package-command $system --wrap --prompt=' $ ' --continuation=' ' --sudo install $system_packages +fi if [ -z "$system" ]; then echo "(none known)" else diff --git a/build/pkgs/calver/distros/package-version.txt b/build/pkgs/calver/distros/package-version.txt deleted file mode 100644 index 42376d1100a..00000000000 --- a/build/pkgs/calver/distros/package-version.txt +++ /dev/null @@ -1 +0,0 @@ -2022.6.26 diff --git a/build/pkgs/sagemath_doc_html/dependencies b/build/pkgs/sagemath_doc_html/dependencies index 9e4732ce372..a72297f8f7d 100644 --- a/build/pkgs/sagemath_doc_html/dependencies +++ b/build/pkgs/sagemath_doc_html/dependencies @@ -1,4 +1,4 @@ -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 +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 # Building the documentation has many dependencies, because all # documented modules are imported and because we use matplotlib to diff --git a/build/pkgs/sphinx_inline_tabs/SPKG.rst b/build/pkgs/sphinx_inline_tabs/SPKG.rst new file mode 100644 index 00000000000..1360f35d925 --- /dev/null +++ b/build/pkgs/sphinx_inline_tabs/SPKG.rst @@ -0,0 +1,16 @@ +sphinx_inline_tabs: Add inline tabbed content to your Sphinx documentation. +=========================================================================== + +Description +----------- + +Add inline tabbed content to your Sphinx documentation. + +License +------- + +Upstream Contact +---------------- + +https://pypi.org/project/sphinx-inline-tabs/ + diff --git a/build/pkgs/sphinx_inline_tabs/checksums.ini b/build/pkgs/sphinx_inline_tabs/checksums.ini new file mode 100644 index 00000000000..f8423958dd5 --- /dev/null +++ b/build/pkgs/sphinx_inline_tabs/checksums.ini @@ -0,0 +1,5 @@ +tarball=sphinx_inline_tabs-VERSION-py3-none-any.whl +sha1=1404e320d0533280355e7e1e71cffd9937015027 +md5=7373d0ebd34be8f9ac2ed62bc63f4582 +cksum=2708358042 +upstream_url=https://pypi.io/packages/py3/s/sphinx_inline_tabs/sphinx_inline_tabs-VERSION-py3-none-any.whl diff --git a/build/pkgs/sphinx_inline_tabs/dependencies b/build/pkgs/sphinx_inline_tabs/dependencies new file mode 100644 index 00000000000..552e1ae7ea8 --- /dev/null +++ b/build/pkgs/sphinx_inline_tabs/dependencies @@ -0,0 +1,4 @@ +sphinx | $(PYTHON_TOOLCHAIN) $(PYTHON) + +---------- +All lines of this file are ignored except the first. diff --git a/build/pkgs/sphinx_inline_tabs/install-requires.txt b/build/pkgs/sphinx_inline_tabs/install-requires.txt new file mode 100644 index 00000000000..53d1db37497 --- /dev/null +++ b/build/pkgs/sphinx_inline_tabs/install-requires.txt @@ -0,0 +1 @@ +sphinx-inline-tabs diff --git a/build/pkgs/sphinx_inline_tabs/package-version.txt b/build/pkgs/sphinx_inline_tabs/package-version.txt new file mode 100644 index 00000000000..67a9bedf97c --- /dev/null +++ b/build/pkgs/sphinx_inline_tabs/package-version.txt @@ -0,0 +1 @@ +2023.4.21 diff --git a/build/pkgs/sphinx_inline_tabs/spkg-configure.m4 b/build/pkgs/sphinx_inline_tabs/spkg-configure.m4 new file mode 100644 index 00000000000..dec6da4736d --- /dev/null +++ b/build/pkgs/sphinx_inline_tabs/spkg-configure.m4 @@ -0,0 +1,3 @@ +SAGE_SPKG_CONFIGURE([sphinx_inline_tabs], [ + SAGE_PYTHON_PACKAGE_CHECK([sphinx_inline_tabs]) +]) diff --git a/build/pkgs/sphinx_inline_tabs/type b/build/pkgs/sphinx_inline_tabs/type new file mode 100644 index 00000000000..a6a7b9cd726 --- /dev/null +++ b/build/pkgs/sphinx_inline_tabs/type @@ -0,0 +1 @@ +standard diff --git a/configure.ac b/configure.ac index 6e124ed6328..ce6c5ea4a71 100644 --- a/configure.ac +++ b/configure.ac @@ -523,7 +523,7 @@ AC_ARG_ENABLE([doc], AS_HELP_STRING([--disable-doc], [disable build of the Sage documentation and packages depending on it]), [ dnl Disable packages needed for docbuilding - 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 + 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 AS_VAR_SET([SAGE_ENABLE_$pkg], [$enableval]) done AS_VAR_IF([enableval], [no], [dnl Disable the docbuild by disabling the install tree for documentation diff --git a/src/doc/en/developer/github.rst b/src/doc/en/developer/github.rst index 79db6ccc3d1..306454407fb 100644 --- a/src/doc/en/developer/github.rst +++ b/src/doc/en/developer/github.rst @@ -123,7 +123,11 @@ https://github.com/alice/sage. Next if you don't have a local Git repo of Sage, then start afresh `cloning your fork -`_:: +`_: + +.. tab:: By HTTPS protocol + + :: [alice@localhost ~]$ git clone https://github.com/alice/sage.git Cloning into 'sage'... @@ -139,7 +143,30 @@ your fork origin https://github.com/alice/sage.git (fetch) origin https://github.com/alice/sage.git (push) -If you already have a local Git repo and only want to link your fork as ``origin`` remote, then do:: +.. tab:: By SSH protocol + + :: + + [alice@localhost ~]$ git clone git@github.com:alice/sage.git + Cloning into 'sage'... + remote: Enumerating objects: 914565, done. + remote: Counting objects: 100% (2738/2738), done. + remote: Compressing objects: 100% (855/855), done. + remote: Total 914565 (delta 1950), reused 2493 (delta 1875), pack-reused 911827 + Receiving objects: 100% (914565/914565), 331.09 MiB | 11.22 MiB/s, done. + Resolving deltas: 100% (725438/725438), done. + Updating files: 100% (9936/9936), done. + [alice@localhost ~]$ cd sage + [alice@localhost sage]$ git remote -v + origin git@github.com:alice/sage.git (fetch) + origin git@github.com:alice/sage.git (push) + + +If you already have a local Git repo and only want to link your fork as ``origin`` remote, then do: + +.. tab:: By HTTPS protocol + + :: [alice@localhost sage]$ git remote add origin https://github.com/alice/sage.git [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 From https://github.com/alice/sage * [new branch] develop -> origin/develop -You also add the Sage repo ``sagemath/sage`` as your remote ``upstream``:: +.. tab:: By SSH protocol + + :: + + [alice@localhost sage]$ git remote add origin git@github.com:alice/sage.git + [alice@localhost sage]$ git remote -v + origin git@github.com:alice/sage.git (fetch) + origin git@github.com:alice/sage.git (push) + [alice@localhost sage]$ git fetch origin + remote: Enumerating objects: 1136, done. + remote: Counting objects: 100% (1084/1084), done. + remote: Compressing objects: 100% (308/308), done. + remote: Total 1136 (delta 825), reused 982 (delta 776), pack-reused 52 + Receiving objects: 100% (1136/1136), 2.62 MiB | 5.30 MiB/s, done. + Resolving deltas: 100% (838/838), completed with 145 local objects. + From git@github.com:alice/sage + * [new branch] develop -> origin/develop + +You also add the Sage repo ``sagemath/sage`` as your remote ``upstream``: + +.. tab:: By HTTPS protocol + + :: [alice@localhost sage]$ git remote add upstream https://github.com/sagemath/sage.git [alice@localhost sage]$ git remote -v @@ -164,19 +213,16 @@ You also add the Sage repo ``sagemath/sage`` as your remote ``upstream``:: upstream https://github.com/sagemath/sage.git (fetch) upstream https://github.com/sagemath/sage.git (push) +.. tab:: By SSH protocol -.. NOTE:: - - If you linked your Git to GitHub by SSH protocol, then do the following - instead to set up remotes:: + :: - [alice@localhost sage]$ git remote add origin git@github.com:alice/sage.git - [alice@localhost sage]$ git remote add upstream git@github.com:sagemath/sage.git - [alice@localhost sage]$ git remote -v - origin git@github.com:alice/sage.git (fetch) - origin git@github.com:alice/sage.git (push) - upstream git@github.com:sagemath/sage.git (fetch) - upstream git@github.com:sagemath/sage.git (push) + [alice@localhost sage]$ git remote add upstream git@github.com:sagemath/sage.git + [alice@localhost sage]$ git remote -v + origin git@github.com:alice/sage.git (fetch) + origin git@github.com:alice/sage.git (push) + upstream git@github.com:sagemath/sage.git (fetch) + upstream git@github.com:sagemath/sage.git (push) To prevent accidental pushes to ``upstream`` (instead of ``origin``), you may want to disable it by running:: diff --git a/src/doc/en/installation/source.rst b/src/doc/en/installation/source.rst index 8ec90a1b022..7aacaef6439 100644 --- a/src/doc/en/installation/source.rst +++ b/src/doc/en/installation/source.rst @@ -90,121 +90,109 @@ approach. .. _sec-installation-from-sources-linux-recommended-installation: -Debian/Ubuntu package installation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Linux system package installation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -On Debian ("buster" or newer) or Ubuntu ("bionic" or newer), we recommend that you -install: +We recommend that you install the following packages, depending on your distribution: -.. literalinclude:: debian.txt +.. tab:: Debian/Ubuntu -If you wish to do Sage development, we recommend that you additionally -install the following: + .. literalinclude:: debian.txt -.. literalinclude:: debian-develop.txt +.. tab:: Fedora/Redhat/CentOS -For all users, we recommend that you install the following system packages, -which provide additional functionality and cannot be installed by Sage: + .. literalinclude:: fedora.txt -.. literalinclude:: debian-recommended.txt +.. tab:: Arch Linux -In addition to these, if you don't want Sage to build optional packages that might -be available from your OS, cf. the growing list of such packages on :trac:`27330`, -install: + .. literalinclude:: arch.txt -.. literalinclude:: debian-optional.txt +.. tab:: OpenSUSE -Fedora/Redhat/CentOS package installation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. literalinclude:: opensuse.txt -On Fedora/Redhat/CentOS, we recommend that you install: +.. tab:: Void Linux -.. literalinclude:: fedora.txt + .. literalinclude:: void.txt If you wish to do Sage development, we recommend that you additionally install the following: -.. literalinclude:: fedora-develop.txt +.. tab:: Debian/Ubuntu -For all users, we recommend that you install the following system packages, -which provide additional functionality and cannot be installed by Sage: + .. literalinclude:: debian-develop.txt -.. literalinclude:: fedora-recommended.txt +.. tab:: Fedora/Redhat/CentOS -In addition to these, if you don't want Sage to build optional packages that might -be available from your OS, cf. the growing list of such packages on :trac:`27330`, -install: + .. literalinclude:: fedora-develop.txt -.. literalinclude:: fedora-optional.txt +.. tab:: Arch Linux -Arch Linux package installation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. literalinclude:: arch-develop.txt -On ArchLinux, we recommend that you install: +.. tab:: OpenSUSE -.. literalinclude:: arch.txt + .. literalinclude:: opensuse-develop.txt -If you wish to do Sage development, we recommend that you additionally -install the following: +.. tab:: Void Linux -.. literalinclude:: arch-develop.txt + .. literalinclude:: void-develop.txt -For all users, we recommend that you install the following system packages, -which provide additional functionality and cannot be installed by Sage: +For all users, we recommend that you install the following system +packages, which provide additional functionality and cannot be +installed by Sage. In particular, this includes :wikipedia:`LaTeX +` and related tools. In addition to a base install of :ref:`TeX +Live `, our lists of system packages below include +everything that is needed for generating the Sage documentation in PDF +format. For converting Jupyter notebooks to PDF, also the document +converter :ref:`pandoc ` is needed. For making +animations, Sage needs to use one of the packages :ref:`FFmpeg +` and :ref:`ImageMagick `. -.. literalinclude:: arch-recommended.txt +.. tab:: Debian/Ubuntu -In addition to these, if you don't want Sage to build optional packages that might -be available from your OS, cf. the growing list of such packages on :trac:`27330`, -install: + .. literalinclude:: debian-recommended.txt -.. literalinclude:: arch-optional.txt +.. tab:: Fedora/Redhat/CentOS -OpenSUSE package installation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. literalinclude:: fedora-recommended.txt -On OpenSUSE, we recommend that you install: +.. tab:: Arch Linux -.. literalinclude:: opensuse.txt + .. literalinclude:: arch-recommended.txt -If you wish to do Sage development, we recommend that you additionally -install the following: +.. tab:: OpenSUSE -.. literalinclude:: opensuse-develop.txt + .. literalinclude:: opensuse-recommended.txt -For all users, we recommend that you install the following system packages, -which provide additional functionality and cannot be installed by Sage: +.. tab:: Void Linux -.. literalinclude:: opensuse-recommended.txt + .. literalinclude:: void-recommended.txt In addition to these, if you don't want Sage to build optional packages that might be available from your OS, cf. the growing list of such packages on :trac:`27330`, install: -.. literalinclude:: opensuse-optional.txt +.. tab:: Debian/Ubuntu -Void Linux package installation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. literalinclude:: debian-optional.txt -On Void Linux, we recommend that you install: +.. tab:: Fedora/Redhat/CentOS -.. literalinclude:: void.txt + .. literalinclude:: fedora-optional.txt -If you wish to do Sage development, we recommend that you additionally -install the following: +.. tab:: Arch Linux -.. literalinclude:: void-develop.txt + .. literalinclude:: arch-optional.txt -For all users, we recommend that you install the following system packages, -which provide additional functionality and cannot be installed by Sage: +.. tab:: OpenSUSE -.. literalinclude:: void-recommended.txt + .. literalinclude:: opensuse-optional.txt -In addition to these, if you don't want Sage to build optional packages that might -be available from your OS, cf. the growing list of such packages on :trac:`27330`, -install: +.. tab:: Void Linux + + .. literalinclude:: void-optional.txt -.. literalinclude:: void-optional.txt .. _section_macprereqs: @@ -1072,56 +1060,3 @@ a single copy of Sage in a multi-user computer network. the installation by yourself:: $ sudo chown -R root SAGE_LOCAL - - -Additional software -------------------- - -The following programs are not strictly required at build time or at run time, -but provide additional capabilities to Sage. We highly recommend a Sage user to -install them. - -LaTeX -^^^^^ - -It is highly recommended that you have :wikipedia:`LaTeX ` installed, -but it is not required. The most popular packaging is `TeX Live -`_, which can be installed following the -directions on their web site. On Linux systems you can alternatively install -your distribution's texlive packages:: - - $ sudo apt-get install texlive # debian - $ sudo yum install texlive # redhat - -or similar commands. In addition to the base TeX Live install, you may -need some optional TeX Live packages, for example -country-specific Babel packages for the localized Sage -documentation. - -Additionally, the following system packages are recommended on Debian/Ubuntu: - -- ``texlive-generic-extra`` (to generate pdf documentation) - -- ``texlive-xetex`` (to convert Jupyter notebooks to pdf) - -- ``latexmk`` (to generate pdf documentation) - -- ``dvipng`` (to render text with LaTeX in Matplotlib) - -pandoc -^^^^^^ - -This is useful to convert Jupyter notebooks to pdf. - -ffmpeg, ImageMagick -^^^^^^^^^^^^^^^^^^^ - -If you don't have either ImageMagick or ffmpeg, you won't be able to view -animations. ffmpeg can produce animations in more different formats than -ImageMagick, and seems to be faster than ImageMagick when creating animated -GIFs. - -``libavdevice-dev`` is a component of ffmpeg to produce animations, and -recommended to install on Debian/Ubuntu. - - diff --git a/src/sage_docbuild/conf.py b/src/sage_docbuild/conf.py index 0ab862c7a13..6b84e772dd1 100644 --- a/src/sage_docbuild/conf.py +++ b/src/sage_docbuild/conf.py @@ -49,6 +49,7 @@ 'sphinx.ext.extlinks', 'sphinx.ext.mathjax', 'sphinx_copybutton', + 'sphinx_inline_tabs', 'IPython.sphinxext.ipython_directive', 'matplotlib.sphinxext.plot_directive', 'jupyter_sphinx',