Opened 9 years ago

Last modified 9 years ago

#10823 closed enhancement

environment variable SAGE_SPKG_INSTALL_DOCS to build and install spkg docs — at Version 15

Reported by: jason Owned by: tbd
Priority: major Milestone: sage-4.7
Component: packages: standard Keywords:
Cc: drkirkby, kcrisman Merged in:
Authors: Reviewers:
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Description (last modified by jason)

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/<SPKG NAME>/

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:

Change History (15)

comment:1 Changed 9 years ago by jason

  • Description modified (diff)

comment:2 Changed 9 years ago by jason

  • Description modified (diff)

comment:3 Changed 9 years ago by jason

  • Description modified (diff)

comment:4 Changed 9 years ago by jason

  • Description modified (diff)
  • Status changed from new to needs_review

comment:5 Changed 9 years ago by jason

  • Description modified (diff)

comment:6 follow-up: Changed 9 years ago by jason

  • Cc drkirkby added

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

comment:7 Changed 9 years ago by jason

  • Description modified (diff)

comment:8 Changed 9 years ago by jason

  • Description modified (diff)

comment:9 Changed 9 years ago by jason

  • Description modified (diff)

comment:10 in reply to: ↑ 6 Changed 9 years ago by drkirkby

Replying to jason:

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.

comment:11 Changed 9 years ago by drkirkby

PS, I think the Sage users (or is it developers?) guide needs to be modified to document the variable. One of the manuals, (I forget which) has all the environment variables documented on one page. So I think the changes to the documentation need to be reviewed here, which will be a trivial review.

Then each .spkg with the changes would need to be on separate tickets.

comment:12 Changed 9 years ago by kcrisman

  • Cc kcrisman added

comment:13 Changed 9 years ago by jason

  • Description modified (diff)

comment:14 Changed 9 years ago by jason

Okay, the doc patches are up here and the description notes which tickets are for the spkgs that I put up earlier.

comment:15 Changed 9 years ago by jason

  • Description modified (diff)
Note: See TracTickets for help on using tickets.