All,
As the general consensus of opinion has been that Sphinx is a suitable tool
for our documentation, I've committed my WIP transcription of the manual
into the git repository under doc/userguide.
I'd like to encourage anyone to contribute documentation, as it's in git
now, it'll have to go through the same approval process as the rest of the
source. This mechanism will suffice for now, until we get a chance to look
into Wiki based contributions as I mentioned earlier in this thread.
In order to build the docs, you'll need Sphinx installed,
http://sphinx.pocoo.org, and to convert the LaTeX to pdf, you'll need a
LaTeX installation. Under Windows, install the full MiKTeX
<http://miktex.org/>installation, under Linux (Ubuntu) I found I had to
install texlive, with a bunch of 'recommeded' and other latex specific
packages. I'll try and identify the real list of texlive packages I
installed on Ubuntu and respond to this thread later. I've included the
Sphinx generate Makefile and make.bat files, so just run "make html" or
"make latex" to build the files.
I need to modify the configuration when I get a moment to build 'out of
source', but that's a minor point, and I wanted to get this committed so
that anyone willing to help can get started.
Cheers
Paul
On Fri, May 14, 2010 at 12:48 AM, Matthias Baas <matthias.baas@...:
> Hi Paul,
>
> Sphinx has become the standard tool for documenting Python packages.
> Besides the Python docs themselves (which Sphinx was written for), I
> have already seen a lot of other packages that use it. I'm also using it
> for cgkit and I'm quite happy with it. It's much more lightweight than
> the previous Latex-based docs. (I particularly like the autodoc feature
> where Sphinx reads the actual docs from Python doc strings which means I
> don't have to duplicate the docs. Obviously this is not relevant for
> Aqsis though)
>
> In addition to Sphinx itself you may also want to install pygments [1]
> to get syntax highlighted source code snippets.
>
> If you want to use maths you have two options, you can have Sphinx
> generate png images (using Latex/dvipng) or you can use jsMath [2] which
> means the maths is rendered in the browser. I've tried that once and it
> worked quite nicely but the jsMath package is fairly large (if I
> remember correctly around 80mb or something like that).
> These two options are for html output only, the math is written using
> Latex syntax, so when generating a pdf, the formulas can be directly put
> into the Latex source files.
>
> Another thing I might eventually do for cgkit is embed videos in the
> documentation. Here you can either use the "raw" directive to directly
> include html in the docs or use the extension in [3] that adds a
> "youtube" directive (I haven't tried that one yet though).
>
> When you start using Sphinx, remember that it generates this "Show
> Source" link on every page. This means you can browse some existing docs
> (such as the Python libs) and check the source whenever you see
> something you don't know yet how it's done in reST. I found that quite
> useful at the beginning.
>
> Cheers,
>
> - Matthias -
>
> [1] http://pygments.org/
> [2] http://www.math.union.edu/~dpvc/jsmath/
> [3] http://countergram.com/youtube-in-rst
>
> Paul Gregory wrote:
> > I've now updated the sample stuff to include the Display API docs,
> > transcribed from the Wiki. It copes reasonably well, I'm sure there are
> > some tweaks we can make if necessary, particularly in the HTML
> > generation via themes. (same filenames, same place).
> >
> > I think the PDF looks pretty good too, might need some work, but most of
> > it can probably be done in the reST source. For example, I've chosen to
> > use definition lists for the members of the structs, there might be a
> > nicer mechanism to use. Alternatively, Sphinx includes some reST
> > extensions specifically for documenting Python (I'm using one of them on
> > the Display API page, cfunction:: ), we could include our own directive
> > extensions if we want, to allow us to nicely and consistently document
> > structs etc.
> >
> > All-in-all, so far I'm very impressed. If I get no negative feedback
> > before next weeks meeting, I'll commit the source to git, so others can
> > start tinkering.
> >
> > On the Wiki side of things, yes, we'd need to switch wiki engine, but it
> > would be to MoinMoin, which is quite well respected, it's the engine
> > used by Ubuntu amongst others. It would mean translating our existing
> > content, but I don't expect that would be too hard. And we wouldn't
> > necessarily need to use reST throughout, as I understand it, we can mix
> > and match reST and standard MoinMoin markup if we want. So we might for
> > example require reST markup only in the documentation submission
> > section. Something to think about, but not essential to resolve before
> > we start using Sphinx for documentation generation, it can come later.
> >
> >
> > Cheers
> >
> >
> >
> > Paul
> >
> > On Wed, May 12, 2010 at 1:24 AM, Chris Foster <chris42f@...
> > <mailto:chris42f@...>> wrote:
> >
> > Hi Paul,
> >
> > I had a browse through both the html and pdf docs you linked, and my
> > initial
> > impression is "when can we start using this?". The html result is
> > much more
> > professionally presented than our current docs on the wiki, and far
> > easier to
> > navigate.
> >
> > The pdf shows that reST->latex works perfectly well for the
> > documentation
> > you've converted so far and gives a very nice looking result. I
> > think another
> > thing we should test is to convert some of the more technical docs
> > to reST &
> > see how they look. In particular, how about the docs in "Aqsis and
> > the RI
> > standard"->"RI Extensions" and/or the docs in the section on the
> > display API?
> >
> > On Wed, May 12, 2010 at 9:01 AM, Paul Gregory <aqsis1@...
> > <mailto:aqsis1@...>> wrote:
> > > Sphinx brings multi-file support to reST, so the source can be
> > organised
> > > neatly into multiple folders and files, making it very manageable.
> > > MoinMoin has a syntax plugin for reST, so we could potentially
> > switch to
> > > reST for our Wiki.
> >
> > Does that mean changing the wiki software then? We use Dokuwiki
> > now, though
> > IIRC most of the plugin customization we have installed is for
> > expanding the
> > wikitext formatting, so reST would probably make that obsolete
> anyway.
> >
> > ~Chris
> >
> >
> >
> >
> > --
> > Paul Gregory
> > http://www.aqsis.org
> >
> >
> > ------------------------------------------------------------------------
> >
> >
> ------------------------------------------------------------------------------
> >
> >
> >
> > ------------------------------------------------------------------------
> >
> > _______________________________________________
> > Aqsis-development mailing list
> > Aqsis-development@...
> > https://lists.sourceforge.net/lists/listinfo/aqsis-development
>
>
>
> ------------------------------------------------------------------------------
>
> _______________________________________________
> Aqsis-development mailing list
> Aqsis-development@...
> https://lists.sourceforge.net/lists/listinfo/aqsis-development
>
--
Paul Gregory
http://www.aqsis.org
|