Trac #29655: Improve build/pkgs/*/SPKG.rst

With #29633, we now generate a full list of packages that Sage uses (with links to documentation - see #27495) for the reference manual from information in `build/pkgs/*/SPKG.rst` (which used to be `SPKG.txt`). The purpose of this ticket is to improve the `SPKG.rst` files and the scripts that transform them to generate a part of the Sage reference manual. 1. If other sources have better information than what is in `build/pkgs`, update `build/pkgs` accordingly. (See https://wiki.sagemath.org/SageWiki) - (done:) https://github.com/sagemath/website/blob/master/conf/packages.yaml (which is used for generating http://www.sagemath.org/links- components.html) - (done:) https://wiki.sagemath.org/spkg (another incomplete list of packages) - `src/doc/en/installation/standard_packages.rst` (yet another incomplete list of packages) 2. Delete/archive the obsolete other sources. - sagemath/website#212 removes `packages.yaml` - https://wiki.sagemath.org/spkg has been cleared 3. Change the titles of the `SPKG.rst` files to use the format "`spkg_name`: Short description". This will improve the table of contents shown in https://doc.sagemath.org/html/en/reference/spkg/index.html, which the Sage website is pointing to after sagemath/website#212 4. Extend `build/bin/sage-spkg-info` and use it to format additional information from `build/pkgs/SPKG/`. 5. In addition to the full alphabetical list of packages, also show the standard packages, the optional packages, and the experimental packages separately. Follow-up: - #31136 Rename SPKGs to match their PyPI name URL: https://trac.sagemath.org/29655 Reported by: mkoeppe Ticket author(s): Matthias Koeppe Reviewer(s): Dima Pasechnik
sagemath · Jan 10, 2021 · f2aca23 · f2aca23
2 parents f1c9633 + 49ad8ae
commit f2aca23
Show file tree

Hide file tree

Showing 296 changed files with 906 additions and 850 deletions.
diff --git a/build/bin/sage-print-system-package-command b/build/bin/sage-print-system-package-command
@@ -119,6 +119,9 @@ case $system:$command in
     freebsd*:install)
         [ -n "$system_packages" ] && echo "${PROMPT}${SUDO}pkg install $system_packages"
         ;;
+    nix*:install)
+        [ -n "$system_packages" ] && echo "${PROMPT}nix-env --install $system_packages"
+        ;;
     pip:install)
         [ -n "$system_packages" ] && echo "${PROMPT}sage -pip install $system_packages"
         ;;

diff --git a/build/bin/sage-spkg b/build/bin/sage-spkg
@@ -146,7 +146,8 @@ lookup_param()
 {
     local param=$1
     local file=$2
-    sed -n "s/^${param} *= *//p" $file
+    # Ignore errors if the file does not exist
+    sed -n "s/^${param} *= *//p" $file 2>/dev/null
 }
 
 write_to_tty()
@@ -317,7 +318,6 @@ fi
 USE_LOCAL_SCRIPTS=yes
 PKG_BASE_VER=`echo $PKG_VER | sed 's/\.p[0-9][0-9]*$//'`
 PKG_NAME_UPSTREAM=`lookup_param tarball "$PKG_SCRIPTS/checksums.ini" | sed "s/VERSION/$PKG_BASE_VER/"`
-echo "Found local metadata for $PKG_NAME"
 
 # Warning for experimental packages
 if [ x`cat "$PKG_SCRIPTS/type"` = x"experimental" -a $INFO = 0 ]; then

diff --git a/build/bin/sage-spkg-info b/build/bin/sage-spkg-info
@@ -15,12 +15,27 @@ for ext in rst txt; do
 done
 if [ -r "$PKG_SCRIPTS/type" ] ; then
     echo
-    echo "== Type =="
+    echo "Type"
+    echo "----"
     echo
     cat "$PKG_SCRIPTS/type"
     echo
 fi
-echo "== Equivalent System Packages =="
+echo
+echo "Version Information"
+echo "-------------------"
+echo
+for a in package-version.txt requirements.txt install-requires.txt; do
+    if [ -f "$PKG_SCRIPTS"/"$a" ]; then
+        echo "$a::"
+        echo
+        sed 's/^/    /' "$PKG_SCRIPTS/$a"
+        echo
+    fi
+done
+echo
+echo "Equivalent System Packages"
+echo "--------------------------"
 echo
 PKG_DISTROS="$PKG_SCRIPTS"/distros
 for system_package_file in "$PKG_DISTROS"/*.txt; do
@@ -40,8 +55,15 @@ for system_package_file in "$PKG_DISTROS"/*.txt; do
                 echo "$system:"
                 ;;
         esac
-        printf "  "
-        sage-print-system-package-command $system --prompt --sudo install $system_packages
+        if [ -n "$OUTPUT_RST" ]; then
+            echo
+            echo ".. CODE-BLOCK:: bash"
+            echo
+        fi
+        sage-print-system-package-command $system --prompt='    $ ' --sudo install $system_packages
+        if [ -n "$OUTPUT_RST" ]; then
+            echo
+        fi
     fi
 done
 if [ -z "$system" ]; then
@@ -52,8 +74,13 @@ else
         echo "If the system package is installed, ./configure will check whether it can be used."
     else
         echo "However, these system packages will not be used for building Sage"
-        echo "because spkg-configure.m4 has not been written for this package;"
-        echo "see https://trac.sagemath.org/ticket/27330"
+        if [ -f "$PKG_SCRIPTS"/install-requires.txt ]; then
+            echo "because using Python site-packages is not supported by the Sage distribution;"
+            echo "see https://trac.sagemath.org/ticket/29023"
+        else
+            echo "because spkg-configure.m4 has not been written for this package;"
+            echo "see https://trac.sagemath.org/ticket/27330"
+        fi
     fi
 fi
 echo
diff --git a/build/pkgs/4ti2/SPKG.rst b/build/pkgs/4ti2/SPKG.rst
@@ -1,5 +1,5 @@
-4ti2
-====
+4ti2: Algebraic, geometric and combinatorial problems on linear spaces
+======================================================================
 
 Description
 -----------
@@ -16,6 +16,8 @@ License
 Upstream Contact
 ----------------
 
+- https://4ti2.github.io/
+
 - Raymond Hemmecke, TU Munich, Germany
 - Matthias Köppe, UC Davis, CA, USA
 

diff --git a/build/pkgs/_recommended/SPKG.rst b/build/pkgs/_recommended/SPKG.rst
@@ -1,5 +1,5 @@
-\_recommended
-=============
+\_recommended: Represents system packages recommended for additional functionality
+==================================================================================
 
 Description
 -----------

diff --git a/build/pkgs/alabaster/SPKG.rst b/build/pkgs/alabaster/SPKG.rst
@@ -1,5 +1,5 @@
-alabaster
-=========
+alabaster: Default theme for the Sphinx documentation system
+============================================================
 
 Description
 -----------
@@ -13,3 +13,8 @@ is selected as the default theme.
 
 Live examples of this theme can be seen on paramiko.org, fabfile.org and
 pyinvoke.org.
+
+Upstream Contact
+----------------
+
+https://alabaster.readthedocs.io/en/latest/
diff --git a/build/pkgs/appnope/SPKG.rst b/build/pkgs/appnope/SPKG.rst
@@ -1,7 +1,12 @@
-appnope
-=======
+appnope: Disable App Nap on OS X
+================================
 
 Description
 -----------
 
 Disable App Nap on OS X 10.9
+
+Upstream Contact
+----------------
+
+https://github.com/minrk/appnope
diff --git a/build/pkgs/arb/SPKG.rst b/build/pkgs/arb/SPKG.rst
@@ -1,5 +1,5 @@
-arb
-===
+arb: Arbitrary-precision floating-point ball arithmetic
+=======================================================
 
 Description
 -----------
@@ -20,7 +20,11 @@ GNU General Public License v2+
 Upstream Contact
 ----------------
 
--  Fredrik Johansson: [email protected]
+ - Fredrik Johansson: [email protected]
+
+ - https://arblib.org/
+
+ - http://github.com/fredrik-johansson/arb/
 
 Dependencies
 ------------

diff --git a/build/pkgs/atlas/SPKG.rst b/build/pkgs/atlas/SPKG.rst
@@ -1,10 +1,10 @@
-ATLAS
-=====
+atlas: Automatically Tuned Linear Algebra Software (BLAS implementation)
+========================================================================
 
 Description
 -----------
 
-This spkg builds ATLAS for Sage.
+Automatically Tuned Linear Algebra Software
 
 License
 -------
@@ -15,6 +15,7 @@ License
 Upstream Contact
 ----------------
 
+-  http://math-atlas.sourceforge.net
 -  Atlas devel mailing list.
 -  Clint Whaley has frequently answered questions from the Sage project
 

diff --git a/build/pkgs/attrs/SPKG.rst b/build/pkgs/attrs/SPKG.rst
@@ -1,5 +1,5 @@
-attrs
-=====
+attrs: Decorator for Python classes with attributes
+===================================================
 
 Description
 -----------

diff --git a/build/pkgs/awali/SPKG.rst b/build/pkgs/awali/SPKG.rst
@@ -1,5 +1,5 @@
-awali
-=====
+awali: Computation of/with finite state machines
+================================================
 
 Description
 -----------

diff --git a/build/pkgs/babel/SPKG.rst b/build/pkgs/babel/SPKG.rst
@@ -1,9 +1,12 @@
-babel
-=====
+babel: Internationalization utilities for Python
+================================================
 
 Description
 -----------
 
-Internationalization utilities
-
 A collection of tools for internationalizing Python applications.
+
+Upstream Contact
+----------------
+
+http://babel.pocoo.org/en/latest/
diff --git a/build/pkgs/backcall/SPKG.rst b/build/pkgs/backcall/SPKG.rst
@@ -1,5 +1,5 @@
-backcall
-========
+backcall: Specifications for callback functions
+===============================================
 
 Description
 -----------

diff --git a/build/pkgs/barvinok/SPKG.rst b/build/pkgs/barvinok/SPKG.rst
@@ -1,5 +1,5 @@
-barvinok
-========
+barvinok: Projections of integer point sets of parametric polytopes
+===================================================================
 
 Description
 -----------

diff --git a/build/pkgs/beautifulsoup4/SPKG.rst b/build/pkgs/beautifulsoup4/SPKG.rst
@@ -0,0 +1,19 @@
+beautifulsoup4: A screen-scraping library
+=========================================
+
+Description
+-----------
+
+Screen-scraping library
+
+License
+-------
+
+MIT
+
+Upstream Contact
+----------------
+
+https://pypi.org/project/beautifulsoup4/
+
+https://www.crummy.com/software/BeautifulSoup/
diff --git a/build/pkgs/benzene/SPKG.rst b/build/pkgs/benzene/SPKG.rst
@@ -1,5 +1,5 @@
-Benzene
-=======
+benzene: Generate fusenes and benzenoids with a given number of faces
+=====================================================================
 
 Description
 -----------
@@ -21,7 +21,9 @@ Upstream Contact
 
 Benzene was written by Gunnar Brinkmann and Gilles Caporossi. This
 version was adapted by Gunnar Brinkmann and Nico Van Cleemput for
-Grinvin. http://www.grinvin.org/
+Grinvin.
+
+http://www.grinvin.org/
 
 Dependencies
 ------------

diff --git a/build/pkgs/biopython/SPKG.rst b/build/pkgs/biopython/SPKG.rst
@@ -0,0 +1,17 @@
+biopython: Tools for computational molecular biology
+====================================================
+
+Description
+-----------
+
+Freely available tools for computational molecular biology.
+
+License
+-------
+
+Upstream Contact
+----------------
+
+https://pypi.org/project/biopython/
+
+http://biopython.org/
diff --git a/build/pkgs/bleach/SPKG.rst b/build/pkgs/bleach/SPKG.rst
@@ -1,5 +1,5 @@
-bleach
-======
+bleach: An HTML-sanitizing tool
+===============================
 
 Description
 -----------

diff --git a/build/pkgs/bliss/SPKG.rst b/build/pkgs/bliss/SPKG.rst
@@ -1,6 +1,5 @@
-
-bliss 0.73+debian-1
-===================
+bliss: Computing automorphism groups and canonical forms of graphs
+==================================================================
 
 Description
 -----------

diff --git a/build/pkgs/boost/SPKG.rst b/build/pkgs/boost/SPKG.rst
@@ -1,5 +1,5 @@
-boost
-=====
+boost: Portable C++ libraries (full set)
+========================================
 
 Description
 -----------

diff --git a/build/pkgs/boost_cropped/SPKG.rst b/build/pkgs/boost_cropped/SPKG.rst
@@ -1,5 +1,5 @@
-Boost
-=====
+boost_cropped: Portable C++ libraries (subset needed for Sage)
+==============================================================
 
 Description
 -----------
@@ -19,8 +19,6 @@ new C++0x Standard now being finalized. C++0x will also include several
 more Boost libraries in addition to those from TR1. More Boost libraries
 are proposed for TR2.
 
-Website: http://www.boost.org/
-
 License
 -------
 
@@ -30,6 +28,8 @@ Boost Software License - see http://www.boost.org/users/license.html
 Upstream Contact
 ----------------
 
+Website: http://www.boost.org/
+
 See mailing list page at http://www.boost.org/community/groups.html
 
 Dependencies

diff --git a/build/pkgs/brial/SPKG.rst b/build/pkgs/brial/SPKG.rst
@@ -1,10 +1,10 @@
-BRiAl
-=====
+brial: Boolean Ring Algebra implementation using binary decision diagrams
+=========================================================================
 
 Description
 -----------
 
-BRiAl is the successor to PolyBoRi.
+BRiAl ("Boolean Ring Algebra") is the successor to PolyBoRi.
 
 The core of PolyBoRi is a C++ library, which provides high-level data
 types for Boolean polynomials and monomials, exponent vectors, as well

diff --git a/build/pkgs/buckygen/SPKG.rst b/build/pkgs/buckygen/SPKG.rst
@@ -1,5 +1,5 @@
-Buckygen
-========
+buckygen: Efficient generation of nonisomorphic fullerenes
+==========================================================
 
 Description
 -----------
@@ -12,15 +12,16 @@ faces are pentagons or hexagons.
 License
 -------
 
-Buckygen is licensed under the GNU General Public License v3 ( June 2007
-)
+Buckygen is licensed under the GNU General Public License v3 (June 2007)
 
 
 Upstream Contact
 ----------------
 
 Buckygen was mainly written by Jan Goedgebeur,
-jan.goedgebeur[at]ugent.be. http://caagt.ugent.be/buckygen/
+jan.goedgebeur[at]ugent.be.
+
+http://caagt.ugent.be/buckygen/
 
 Dependencies
 ------------