#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: David Kirkby | Merged:
Work_issues: |
----------------------------+-----------------------------------------------
Comment(by jason):
Replying to [comment:17 drkirkby]:
> 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.
>
Thanks very much for your time and thoughtful care in reviewing this
(twice, even!)
> From what I recall
>
> * 'make' should be $MAKE
> * 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.
You're right that I just put example instructions up there. Instead, I'll
just put a comment (I've modified the description accordingly).
> * 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.
Okay, though it's not really in the direct scope of this ticket, since I'm
modifying the file anyway, I'll throw this in too.
> * 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.
>
> 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/
Do you happen to know what file this is generated from? I'd also consider
this a separate ticket, since there are questions about how to deal with
this on sagemath.org, and the fact that the link probably ought not be
there if we don't generate the docs, maybe.
> * 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.
Fix coming up.
> * 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/}}}
I didn't put the $ since $SPKG_NAME is not a variable that works in the
spkg-install file. My hope was to help them realize that they needed to
manually fill in SPKG_NAME. I'll put a note to that effect.
>
> 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.
Personally, in the spkgs I modified, I just built the html documentation
unless the default package documentation-building command built pdf too (I
believe pari was that way). I think both might be best, but having just
html documentation built requires less (latex is not required, IIRC).
>
> Overall though, I think this is a good idea.
Thanks!
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/10823#comment:20>
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.
