environment variable SAGE_SPKG_INSTALL_DOCS to build and install spkg docs

[jasongrout]

There are lots of times when it would be convenient to have the documentation of various spkgs installed in a local or system Sage installation. For example, it seems that I'm always wishing that I had that at an airport or on an airplane. At one point a long time ago, we had an extradocs spkg, but it was never maintained. So here is a proposal:

When building an spkg, if the SAGE_SPKG_INSTALL_DOCS environment variable is yes, then the docs are built (if available in the spkg) and are installed in $SAGE_ROOT/local/share/doc//

For example, numpy includes the docs with the sources. I'd like to insert the following at the bottom of the numpy spkg-install:

if [ "x$SAGE_SPKG_INSTALL_DOCS" = xyes ] ; then
    cd doc
    make html
    if [ $? -ne 0 ]; then
    echo "Error building numpy docs."
    exit 1
    fi
    mkdir -p $SAGE_ROOT/local/share/doc/numpy
    mv build/html $SAGE_ROOT/local/share/doc/numpy
fi

This builds the numpy docs and makes a directory $SAGE_ROOT/local/share/doc/numpy/html/ that contains the standalone html documentation for numpy.

Here are a few updated spkgs:

• numpy: Make numpy support SAGE_SPKG_INSTALL_DOCS #10826
• cython: Make cython support SAGE_SPKG_INSTALL_DOCS #10827
• matplotlib: Make matplotlib support SAGE_SPKG_INSTALL_DOCS #10828
• mpmath: Make mpmath support SAGE_SPKG_INSTALL_DOCS #10829
• pari: Make pari support SAGE_SPKG_INSTALL_DOCS #10830
• gap: Make gap support SAGE_SPKG_INSTALL_DOCS #10825
• python: Make python support SAGE_SPKG_INSTALL_DOCS #10831
• sagetex: Make SageTeX support SAGE_SPKG_INSTALL_DOCS #10908

CC: @sagetrac-drkirkby @kcrisman

Component: packages: standard

Author: Jason Grout

Reviewer: David Kirkby

Merged: sage-4.7.alpha1

Issue created by migration from https://trac.sagemath.org/ticket/10823

[jasongrout]

Description changed:

--- 
+++ 
@@ -18,3 +18,7 @@
 ```
 This builds the numpy docs and makes a directory $SAGE_ROOT/local/share/doc/numpy/html/ that contains the standalone html documentation for numpy.
 
+Here are a few updated spkgs:
+
+* numpy: http://sage.math.washington.edu/home/jason/numpy-1.5.1.p0.spkg
+

[jasongrout]

Description changed:

--- 
+++ 
@@ -20,5 +20,5 @@
 
 Here are a few updated spkgs:
 
-* numpy: http://sage.math.washington.edu/home/jason/numpy-1.5.1.p0.spkg
+* numpy: http://sage.math.washington.edu/home/jason/numpy-1.5.1.p0.spkg (depends on #10792)
 

[jasongrout]

Description changed:

--- 
+++ 
@@ -13,7 +13,7 @@
     exit 1
     fi
     mkdir -p $SAGE_ROOT/local/share/doc/numpy
-    cp -r build/html $SAGE_ROOT/local/share/doc/numpy
+    mv build/html $SAGE_ROOT/local/share/doc/numpy
 fi
 ```
 This builds the numpy docs and makes a directory $SAGE_ROOT/local/share/doc/numpy/html/ that contains the standalone html documentation for numpy.
@@ -21,4 +21,5 @@
 Here are a few updated spkgs:
 
 * numpy: http://sage.math.washington.edu/home/jason/numpy-1.5.1.p0.spkg (depends on #10792)
+* cython: http://sage.math.washington.edu/home/jason/cython-0.14.1.p0.spkg (depends on #10493)
 

[jasongrout]

Description changed:

--- 
+++ 
@@ -22,4 +22,4 @@
 
 * numpy: http://sage.math.washington.edu/home/jason/numpy-1.5.1.p0.spkg (depends on #10792)
 * cython: http://sage.math.washington.edu/home/jason/cython-0.14.1.p0.spkg (depends on #10493)
-
+* matplotlib: http://sage.math.washington.edu/home/jason/matplotlib-1.0.1.p0.spkg (depends on #10588)

[jasongrout]

Description changed:

--- 
+++ 
@@ -9,7 +9,7 @@
     cd doc
     make html
     if [ $? -ne 0 ]; then
-    echo "Error building numpy."
+    echo "Error building numpy docs."
     exit 1
     fi
     mkdir -p $SAGE_ROOT/local/share/doc/numpy

[jasongrout]

comment:6

CCing our resident shell script expert for comments: David, is there anything else that should be done in the above snippet of shell script?

[jasongrout]

Description changed:

--- 
+++ 
@@ -23,3 +23,4 @@
 * numpy: http://sage.math.washington.edu/home/jason/numpy-1.5.1.p0.spkg (depends on #10792)
 * cython: http://sage.math.washington.edu/home/jason/cython-0.14.1.p0.spkg (depends on #10493)
 * matplotlib: http://sage.math.washington.edu/home/jason/matplotlib-1.0.1.p0.spkg (depends on #10588)
+* mpmath: http://sage.math.washington.edu/home/jason/mpmath-0.15.p0.spkg

[jasongrout]

Description changed:

--- 
+++ 
@@ -24,3 +24,4 @@
 * cython: http://sage.math.washington.edu/home/jason/cython-0.14.1.p0.spkg (depends on #10493)
 * matplotlib: http://sage.math.washington.edu/home/jason/matplotlib-1.0.1.p0.spkg (depends on #10588)
 * mpmath: http://sage.math.washington.edu/home/jason/mpmath-0.15.p0.spkg
+* pari: http://sage.math.washington.edu/home/jason/pari-2.4.3.alpha.p1.spkg

[jasongrout]

Description changed:

--- 
+++ 
@@ -25,3 +25,4 @@
 * matplotlib: http://sage.math.washington.edu/home/jason/matplotlib-1.0.1.p0.spkg (depends on #10588)
 * mpmath: http://sage.math.washington.edu/home/jason/mpmath-0.15.p0.spkg
 * pari: http://sage.math.washington.edu/home/jason/pari-2.4.3.alpha.p1.spkg
+* gap: http://sage.math.washington.edu/home/jason/gap-4.4.12.p5.spkg

[sagetrac-drkirkby]

comment:10

Replying to @jasongrout:

CCing our resident shell script expert for comments: David, is there anything else that should be done in the above snippet of shell script?

I would indent the

    echo "Error building numpy docs."
    exit 1

for clarity. Apart from that, it looks OK. It will put the docs in a directory

$SAGE_ROOT/local/share/doc/numpy/html

not

$SAGE_ROOT/local/share/doc/numpy

but I think that's a good idea, as some docs might be in pdf, others in html etc.

I think it would be more normal to copy the files, rather than move them, so the build directory remains intact. (It usually gets deleted anyway, but there are ways of saving the contents).

Overall, I think this is a good proposal. Lots of programs used by Sage have documentation which we don't use. There may be other tools needed to generate some of the files - (GNU info for example). In cases like that, it might be worth checking if the right tool existed.