#10823: environment variable SAGE_SPKG_INSTALL_DOCS to build and install spkg
docs
---------------------------+------------------------------------------------
Reporter: jason | Owner: tbd
Type: enhancement | Status: needs_work
Priority: major | Milestone: sage-4.6.2
Component: packages | Keywords:
Author: Jason Grout | Upstream: N/A
Reviewer: | Merged:
Work_issues: |
---------------------------+------------------------------------------------
Changes (by drkirkby):
* status: needs_review => needs_work
Comment:
Sorry for the delay. I spent about an hour replying to this yesterday when
my wife accidentally pulled the power cord from my laptop, which did not
have a battery in it at the time. So it was all lost.
From what I recall
* 'make' should be $MAKE
* There should be a link added to this page http://www.sagemath.org/doc/
(which is generated from the docs in Sage) to show the place where the new
documentation can be found.
* The line with {{{ echo "SAGE_LOCAL undefined ... exiting";}}} in
{{{doc/en/developer/producing_spkgs.rst}}} has an extra semi-colon on the
end. Since that is in the same file as here, that might as well be fixed
at the same time. Also replace 'make' by $MAKE there.
* The ticket description shows {{{make html}}} but the patch {{{make
doc}}}. There is no standard way of creating documentation. Hence the
developers guide should make it clearer that this section of {{{spk-
install}}} will probably need changing depending on the package, and
should not be copied verbatim and expected to work.
* There's a possibility that building some of the documentation may
require external programs like GNU info, LaTeX. makeinfo etc. This needs
to be mentioned in the docs.
* The patch says the documentation gets installed in the file
{{{$SAGE_ROOT/local/share/doc/SPKG_NAME/}}}. I think there should be in
front of $SPKG_NAME - just as with SAGE_ROOT. Also, a more accurate
description is that the docs are installed in one or more directories
below {{{$SAGE_ROOT/local/share/doc/SPKG_NAME/}}}
Clearly adding the code to the packages is quite simple, but unless it is
well documented it's not going to be much use. People must be able to find
the documentation, which I think will be most easily done if on the main
page http://www.sagemath.org/doc/
Have you given thought to what is to be done if one can build both HTML
and PDF docs? I suggesting building both might be best, but I don't know.
Overall though, I think this is a good idea.
Dave
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/10823#comment:17>
Sage <http://www.sagemath.org>
Sage: Creating a Viable Open Source Alternative to Magma, Maple, Mathematica,
and MATLAB
--
You received this message because you are subscribed to the Google Groups
"sage-trac" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/sage-trac?hl=en.
