documentation changes
Jason Grout
using Latex). How do I build a new manual to see my changes? Going to
the doc directory and typing "make pdf" seems to just pick up the old
sage.graphs.graph.tex file and not generate a new one from the python
source. Did I miss something in the documentation?
Thanks,
Jason
David Joyner
docstrings on the reference manual?
At this point, only William can do that, I believe.
+++++++++++++++++
Jason Grout
> I think you are talking about the effect of your new
> docstrings on the reference manual?
> At this point, only William can do that, I believe.
Yes, seeing in the reference manual the effect of changing docstrings in
the source is what I'm referring to. I just wanted to double-check that
my latex formatting looked all right.
Thanks,
Jason
William Stein
> using Latex). How do I build a new manual to see my changes?
cd SAGE_ROOT/devel/doc/ref
./build_pdf
That will create ref.pdf, which you can view. This *requires* that you
have latex2html correctly installed, which -- due to its screwy
license -- often isn't installed on machines by default.
> Going to
> the doc directory and typing "make pdf" seems to just pick up the old
> sage.graphs.graph.tex file and not generate a new one from the python
> source.
That would also work, but you have to first do
./update
in the SAGE_ROOT/devel/doc/ref/ directory.
> Did I miss something in the documentation?
No, you didn't miss anything, since the build
system is unfortunately not really documented.
There is a minimal README.txt in
SAGE_ROOT/devel/doc/ref/
If anybody understands the build system and
wants to document the above sort of thing, please
post a patch to trac against the doc repository.
William
David Joyner
>
> On 9/21/07, Jason Grout <jason...@creativetrax.com> wrote:
> > I changed some of the documentation in graphs/graph.py (formatted it
> > using Latex). How do I build a new manual to see my changes?
>
> cd SAGE_ROOT/devel/doc/ref
> ./build_pdf
>
> That will create ref.pdf, which you can view. This *requires* that you
> have latex2html correctly installed, which -- due to its screwy
> license -- often isn't installed on machines by default.
Would this method also work for docstrings files which are not included in the
reference manual? (Ie, for newly created *.py files.)
William Stein
> On 9/21/07, William Stein <wst...@gmail.com> wrote:
> > On 9/21/07, Jason Grout <jason...@creativetrax.com> wrote:
> > > I changed some of the documentation in graphs/graph.py (formatted it
> > > using Latex). How do I build a new manual to see my changes?
> >
> > cd SAGE_ROOT/devel/doc/ref
> > ./build_pdf
> >
> > That will create ref.pdf, which you can view. This *requires* that you
> > have latex2html correctly installed, which -- due to its screwy
> > license -- often isn't installed on machines by default.
>
>
> Would this method also work for docstrings files which are not included in the
> reference manual? (Ie, for newly created *.py files.)
No, this will certainly not work for such docstrings -- I would like
something that does. This should be put into a trac ticket.
By the way, you *can* simply add the new file by
making an empty file with the right now (but replace _ by -).
Then include it in ref.tex.
There is actually now a massive amount of code that has
lots of documentation but isn't in the reference manual.
This needs to change. Of course, then the reference manual
will go from 2,200 pages to 4,000 pages...
William
>
> >
> > > Going to
> > > the doc directory and typing "make pdf" seems to just pick up the old
> > > sage.graphs.graph.tex file and not generate a new one from the python
> > > source.
> >
> > That would also work, but you have to first do
> > ./update
> > in the SAGE_ROOT/devel/doc/ref/ directory.
> >
> > > Did I miss something in the documentation?
> >
> > No, you didn't miss anything, since the build
> > system is unfortunately not really documented.
> >
> > There is a minimal README.txt in
> > SAGE_ROOT/devel/doc/ref/
> >
> > If anybody understands the build system and
> > wants to document the above sort of thing, please
> > post a patch to trac against the doc repository.
> >
> > William
> >
> > >
> >
>
> >
>
--
William Stein
Associate Professor of Mathematics
University of Washington
http://wstein.org
Jason Grout
> On 9/21/07, David Joyner <wdjo...@gmail.com> wrote:
>> On 9/21/07, William Stein <wst...@gmail.com> wrote:
>>> On 9/21/07, Jason Grout <jason...@creativetrax.com> wrote:
>>>> I changed some of the documentation in graphs/graph.py (formatted it
>>>> using Latex). How do I build a new manual to see my changes?
>>> cd SAGE_ROOT/devel/doc/ref
>>> ./build_pdf
>>>
>>> That will create ref.pdf, which you can view. This *requires* that you
>>> have latex2html correctly installed, which -- due to its screwy
>>> license -- often isn't installed on machines by default.
>>
>> Would this method also work for docstrings files which are not included in the
>> reference manual? (Ie, for newly created *.py files.)
>
> No, this will certainly not work for such docstrings -- I would like
> something that does. This should be put into a trac ticket.
>
> By the way, you *can* simply add the new file by
> making an empty file with the right now (but replace _ by -).
> Then include it in ref.tex.
>
> There is actually now a massive amount of code that has
> lots of documentation but isn't in the reference manual.
> This needs to change. Of course, then the reference manual
> will go from 2,200 pages to 4,000 pages...
Thanks for your replies! I'm now able to build the documentation and
get my changes into my version of the reference manual.
As for reference material, I consider the reference manual the
comprehensive unabridged dictionary of SAGE. You know, something you
could curl up on a couch with on a rainy day :). I'd love to see it
expand to twice its size if the documentation is there.
Also, an observation:
I updated the reference tex files by doing:
cd /sage/devel/doc/ref/
./update
cd ..
make pdf
However, it claimed that there was nothing to be done, since everything
was up to date. I had to make clobber before it would build the
documentation again.
Is there a way to have the ./update command touch a file which was then
a dependency for the make pdf/html/etc commands? That way, running
./update would force make to rerun the pdf/html/etc generation.
I'll open up a trac ticket. If this suggestion is a bad idea, feel free
to close the ticket.
Thanks,
Jason
William Stein
> Thanks for your replies! I'm now able to build the documentation and
> get my changes into my version of the reference manual.
>
> As for reference material, I consider the reference manual the
> comprehensive unabridged dictionary of SAGE. You know, something you
> could curl up on a couch with on a rainy day :). I'd love to see it
> expand to twice its size if the documentation is there.
Same here.
> Also, an observation:
>
> I updated the reference tex files by doing:
>
> cd /sage/devel/doc/ref/
> ./update
> cd ..
> make pdf
>
> However, it claimed that there was nothing to be done, since everything
> was up to date. I had to make clobber before it would build the
> documentation again.
>
> Is there a way to have the ./update command touch a file which was then
> a dependency for the make pdf/html/etc commands? That way, running
> ./update would force make to rerun the pdf/html/etc generation.
>
> I'll open up a trac ticket. If this suggestion is a bad idea, feel free
> to close the ticket.
The main reason for
./build_pdf
or
./build_dvi
was that I couldn't figure out how to do exactly what you suggest
above reliably. If somebody can figure it out, that would be
appreciated.
Incidentally, the whole sage documentation structure started from
the Python documentation (probably Python 2.4), which I just
motivated to be the Sage manuals instead. I had experimented
a lot with automated tools like epydoc, etc., and found that they
break a lot on the incredibly complicated Sage library, they don't
play well with Cython code (which is nearly 1/3rd of Sage?), and
and they just don't feel as well organized and readable as something
that a person has to spend time putting together. The current
documentation -- though not comprehensive -- tends to only
have things in it that are "reasonably usable and stable", so the
stuff that epydoc would pick up that is really a mess isn't there.
That said, *pydoc has probably improved a lot in the last 2 years
(since I last used it), and it would be good to have some 100%
complete autogenerated variant of the reference manual in
addition to the current more manually organized one.
William
Jason Grout
> Incidentally, the whole sage documentation structure started from
> the Python documentation (probably Python 2.4), which I just
> motivated to be the Sage manuals instead. I had experimented
> a lot with automated tools like epydoc, etc., and found that they
> break a lot on the incredibly complicated Sage library, they don't
> play well with Cython code (which is nearly 1/3rd of Sage?), and
> and they just don't feel as well organized and readable as something
> that a person has to spend time putting together. The current
> documentation -- though not comprehensive -- tends to only
> have things in it that are "reasonably usable and stable", so the
> stuff that epydoc would pick up that is really a mess isn't there.
>
> That said, *pydoc has probably improved a lot in the last 2 years
> (since I last used it), and it would be good to have some 100%
> complete autogenerated variant of the reference manual in
> addition to the current more manually organized one.
Is one requirement for any such system the ability to deal with math in
the documentation? After browsing for a little bit, it seems like that
is a sticky point that many systems don't address, other than pydoc,
though epydoc does have some sort of construct for math ( X{x+y} ).
It's nice now to have the documentation in latex so that we can write a
mathematical explanation.
-Jason
William Stein
>
> > Incidentally, the whole sage documentation structure started from
> > the Python documentation (probably Python 2.4), which I just
> > motivated to be the Sage manuals instead. I had experimented
> > a lot with automated tools like epydoc, etc., and found that they
> > break a lot on the incredibly complicated Sage library, they don't
> > play well with Cython code (which is nearly 1/3rd of Sage?), and
> > and they just don't feel as well organized and readable as something
> > that a person has to spend time putting together. The current
> > documentation -- though not comprehensive -- tends to only
> > have things in it that are "reasonably usable and stable", so the
> > stuff that epydoc would pick up that is really a mess isn't there.
> >
> > That said, *pydoc has probably improved a lot in the last 2 years
> > (since I last used it), and it would be good to have some 100%
> > complete autogenerated variant of the reference manual in
> > addition to the current more manually organized one.
>
> Is one requirement for any such system the ability to deal with math in
> the documentation?
That would be nice and is a big advantage of the current latex system.
That said, something autogenerated with ugly math in it (not typeset)
would be useful, probably.
> After browsing for a little bit, it seems like that
> is a sticky point that many systems don't address, other than pydoc,
> though epydoc does have some sort of construct for math ( X{x+y} ).
> It's nice now to have the documentation in latex so that we can write a
> mathematical explanation.
No matter what, the input in doctests will be latex notation. I'm definitely
not going to consider using some funky math notation for the documentation.
William