Clawpack documentation on GitHub
Randall J. LeVeque
to organize it.
If you only plan to read documentation and not contribute to it then
you don't need to read much further, but you might want to look at the
pages linked from
http://clawpack.github.com/
and give feedback on the new Sphinx style. It now has a different
look than the default Sphinx style we used to use. Many links are
currently broken, in particular to examples and the gallery.
Regarding organization, my current plan is the following:
Each project (separate repository) has a doc subdirectory that can
include .rst files for Sphinx documentation for that project,
including index.rst and a separate conf.py and css files, layout.html,
etc. for formatting if desired, so that the documentation for a
project can stand on its own such as what David Ketcheson has put in
sharpclaw/doc.
The doc repository has a subdirectory doc/doc that contains .rst files
for the general introductory pages about Clawpack. Running the Python
script linkall.py in this directory creates soft links to all the
other repos/doc directories, so that the general Clawpack
documentation created here also incorporates all the documentation
from the separate repositories, such as sharpclaw.
Doing 'make html' in the doc/doc directory creates html files in
doc/doc/_build/html. To post these on the website, these files must
be copied to a different repository, to clawpack.github.com/doc, and
then pushed to GitHub. These are the pages that appear at
http://clawpack.github.com/doc/index.html
I also did 'make html' in the sharpclaw/doc directory and copied the
html files from sharpclaw/doc/_build/html to
clawpack.github.com/sharpclaw/doc and after pushing to GitHub these
pages appear at
http://clawpack.github.com/sharpclaw/doc/index.html
Note that these stand-along sharpclaw pages contain the same
information as in the Clawpack documentation at
http://clawpack.github.com/doc/sharpclaw_doc/index.html
but is formatted differently.
Hope that's not too confusing. Suggestions welcome!
- Randy
David Ketcheson
which is nice. In fact, I like it better than the style I'm using!
Thanks for taking the trouble to build my documentation with the new
style.
The only thing that concerns me is that every page says 'Clawpack
documentation' at the top. Since most of the doc pages for Sharpclaw
(for instance) don't say 'SharpClaw' at the top, it's easy to lose the
context of what you're looking at. For instance, opening
http://clawpack.github.com/doc/sharpclaw_doc/future.html (without
reading carefully the URL) is a bit confusing -- one immediately
thinks these are future plans for Clawpack, rather than SharpClaw.
Also, the 'Contents' link on that page, for instance, takes you all
the way back up to the global contents, making it quite difficult to
find your way back into the SharpClaw documentation. Is there an easy
way to make these things (the header and links) more local?
-David
Randall J. LeVeque
Yes, that's a problem with the fact that these pages are all built
with a single 'make html' in the doc/doc directory, and so they all
use the same conf.py and css pages. The sharpclaw documentation is
easily incorporated by having a sym link from doc/doc/sharpclaw_doc to
sharpclaw/doc and the line
sharpclaw_doc/index
in the doc/doc/index.rst file, but then these .rst pages are handled
the same way as all the others in doc/doc.
An alternative would be to have doc/doc/index.rst contain a line
sharpclaw
and the file doc/doc/sharpclaw.rst simply contain a brief description
of SharpClaw and a pointer to the webpages for its documentation.
This might make the most sense for sharpclaw and petclaw. For visclaw
I'd like the documentation to just show up as part of the Clawpack
documentation.
Another way to accomplish what you want in principle is to use
intersphinx so that pages of the Clawpack documentation can include
links to sharpclaw sections using the :ref: notation and will point to
a separate set of documentation, but I haven't yet figured out how to
do that and I'm not sure it's necessary. If someone wants to figure
it out, this might be nice in the future. There's a description at
http://sphinx.pocoo.org/ext/intersphinx.html
but what I couldn't figure out is what form the objects.inv file should have.
- Randy
> --
> You received this message because you are subscribed to the Google Groups "claw-dev" group.
> To post to this group, send email to claw...@googlegroups.com.
> To unsubscribe from this group, send email to claw-dev+u...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/claw-dev?hl=en.
>
>
David Ketcheson
> An alternative would be to have doc/doc/index.rst contain a line
> sharpclaw
> and the file doc/doc/sharpclaw.rst simply contain a brief description
> of SharpClaw and a pointer to the webpages for its documentation.
>
> This might make the most sense for sharpclaw and petclaw.
be nice to have a 'common look and feel'. I've posted a new set of
pages here:
http://clawpack.github.com/sharpclaw/doc2/index.html
These use your conf.py and .css, but say 'SharpClaw' documentation at
the top and have some local links (which don't work at present). I'd
probably leave the Clawpack logo unless I get around to making a logo
for SharpClaw at some point.
> Another way to accomplish what you want in principle is to use
> intersphinx so that pages of the Clawpack documentation can include
> links to sharpclaw sections using the :ref: notation and will point to
> a separate set of documentation, but I haven't yet figured out how to
> do that and I'm not sure it's necessary. If someone wants to figure
> it out, this might be nice in the future. There's a description at
> http://sphinx.pocoo.org/ext/intersphinx.html
> but what I couldn't figure out is what form the objects.inv file should have.
believe the objects.inv file gets created automatically (you already
have one for Clawpack, and it's binary). Haven't gotten around to
trying it yet.
-David
David Ketcheson
> An alternative would be to have doc/doc/index.rst contain a line
> sharpclaw
> and the file doc/doc/sharpclaw.rst simply contain a brief description
> of SharpClaw and a pointer to the webpages for its documentation.
Tell me what you think.
I want to use intersphinx still but haven't set it up yet.
Two additional comments:
-The AMRClaw docs aren't on github yet, so those don't appear anymore.
-We are using slightly different versions of Sphinx (Randy: 1.0.4;
David: 1.0.7), which seems to have resulted in insignificant changes
(like whitespace) to all of the documentation files when I rebuilt
them. This probably doesn't matter since you would go back to
the .rst files if you were inspecting old versions anyway.
David Ketcheson
Github, I don't think it's the best option.
The process requires building the docs in one repository, copying them
to another, committing, and pushing.
The commit and push seem like an unnecessary complication to me, since
keeping the generated html files under version
control doesn't yield any benefit that I can see. I much prefer the
idea of needing only to build the docs and upload them;
this also has the advantage of being able to be performed by a script.
An even easier option is readthedocs.org. That site grabs your
documentation directly from your Github
repo whenever you push, rebuilds it, and hosts it. Take a look at
http://pyclaw.readthedocs.org/.
That took me all of 30 seconds to set up. There are some problems,
though: it isn't using our custom CSS
(though it's supposed to be possible) and the autodoc fails in some
cases because it needs to import
things like numpy, which obviously aren't distributed with pyclaw.
But if we could sort these things out,
it seems like a very nice solution.
-David
Randall J. LeVeque
Not only because of the extra complications David mentions, but also
because the main Clawpack documentation is currently set up to contain
many pointers to sample codes and the plots they produce. For
example, if you go to one of the gallery pages from
http://kingkong.amath.washington.edu/clawpack/users/apps.html
you can click on a figure to go to the plots directory, or on the
README link to go to the html versions of the source code. I think
this is a nice way to document the codes, but building the
documentation then requires running all the codes and keeping all the
plots and html files. This creates files that are 10 times larger
than the source.
I certainly don't want to upload all this to Github and there's no
need for it to be under version control. So my current thought is
that all the documentation will be hosted elsewhere, e.g. on the UW
system (but not kingkong, which has severe webserving issues at the
moment).
The disadvantage of this is that if others maintain documentation for
SharpClaw, say, somewhere else, then it will not all fit together so
nicely.
I looked briefly at readthedocs.org and I don't think it would easily
deal with the issue of needing to include all the plots and source
code files as well as the html's that are build automatically by
sphinx.
Suggestions?
- Randy