future of mpl documentation

There was some discussion a while back concerning upcoming changes to the mpl
documentation: moving the docs into the trunk and updating the website. I
can't find the thread now, could anyone summarize the current thinking?
Ondrej Certik recently implemented a sphinx-based documentation for ipython1
(see http://ipython.scipy.org/doc/ipython1/html/ and
http://ipython.scipy.org/doc/ipython1/ipython1.pdf), I wonder if we should
consider doing the same for matplotlib.

I haven't had nearly as much time to contribute to matplotlib as I did when I
was still in grad school, but I think I will have some free time starting in
May and would like to contribute some more over the summer. Now is probably a
good time to start considering summer projects.

Darren

For those of you wondering "what is sphinx?" this will save you a few
seconds of searching: http://sphinx.pocoo.org/

The output looks really nice.

Darren Dale wrote:

···

There was some discussion a while back concerning upcoming changes to the mpl
documentation: moving the docs into the trunk and updating the website. I
can't find the thread now, could anyone summarize the current thinking?
Ondrej Certik recently implemented a sphinx-based documentation for ipython1
(see http://ipython.scipy.org/doc/ipython1/html/ and
http://ipython.scipy.org/doc/ipython1/ipython1.pdf), I wonder if we should
consider doing the same for matplotlib.

I haven't had nearly as much time to contribute to matplotlib as I did when I
was still in grad school, but I think I will have some free time starting in
May and would like to contribute some more over the summer. Now is probably a
good time to start considering summer projects.

Darren

-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2008.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
matplotlib-devel List Signup and Options

I'm definitely up for this or something close to it. We definitely
want rest based docs which live in svn alongside the src distribution.
If something like sphinx on top of it makes for better documents, I'm
all for it. You may have seen that over the weekend I added a couple
of API rst documents to the doc subdir, with some basic make.py
support for building them into PDFs. If you or anyone would like to
take a stab at getting a sphinx implementation going, have at it.

JDH

···

On Tue, Mar 25, 2008 at 7:38 AM, Darren Dale <darren.dale@...143...> wrote:

There was some discussion a while back concerning upcoming changes to the mpl
documentation: moving the docs into the trunk and updating the website. I
can't find the thread now, could anyone summarize the current thinking?
Ondrej Certik recently implemented a sphinx-based documentation for ipython1
(see http://ipython.scipy.org/doc/ipython1/html/ and
http://ipython.scipy.org/doc/ipython1/ipython1.pdf), I wonder if we should
consider doing the same for matplotlib.

Hey guys,

sorry for the silence, mostly on travel. I just wanted to mention
that the sphinx machinery seems quite nice, in particular it produces
both high-quality pdf and client-side searchable html. This is great,
because it measn that the entire doc set is automatically searchable
for the users in a convenient manner, even when running offline and
without the need for any special server config (and in a more
civilized fashion than brute-forcing grep searches).

Also, Sympy (led by Ondrej), ipython, mayavi2 and at least
neuroimaging.scipy.org have all committed to using this system, and we
hope in the future numpy and scipy will follow suit (at least Jarrod
Millman and Stefan van der Walt, who are doing lots of work on those,
are fully on board with the idea). It would be really nice if all
these projects could offer unified, consistent docs to their users,
and having MPL jump along would be great.

Cheers,

f

Fernando Perez wrote:

Hey guys,

sorry for the silence, mostly on travel. I just wanted to mention
that the sphinx machinery seems quite nice, in particular it produces
both high-quality pdf and client-side searchable html. This is great,
because it measn that the entire doc set is automatically searchable
for the users in a convenient manner, even when running offline and
without the need for any special server config (and in a more
civilized fashion than brute-forcing grep searches).

Also, Sympy (led by Ondrej), ipython, mayavi2 and at least
neuroimaging.scipy.org have all committed to using this system, and we
hope in the future numpy and scipy will follow suit (at least Jarrod
Millman and Stefan van der Walt, who are doing lots of work on those,
are fully on board with the idea). It would be really nice if all
these projects could offer unified, consistent docs to their users,
and having MPL jump along would be great.
  
How stable is the API? We (Enthought) use endo, a custom tool build on top of docutils, to generate our docs currently. We have talked about changing tools in the past, but the need to extend the tools to understand Traits has held us back.

Thanks,
Bryce

Sphinx is not automated API documentation, like Endo or Epidoc. It is for
manual writing of documentation. It does not compete with Endo or Epidoc,
but complements them by taking a set of rst files and compiling both a
set of searchable web pages, and an indexed pdf for print.

Ga�l

···

On Tue, Mar 25, 2008 at 06:04:41PM -0500, bryce hendrix wrote:

How stable is the API? We (Enthought) use endo, a custom tool build on
top of docutils, to generate our docs currently. We have talked about
changing tools in the past, but the need to extend the tools to
understand Traits has held us back.

Well, I have read that elsewhere, maybe even on the sphinx website, but you
actually can use it to document the API. I haven't done a complete comparison
of epydoc and sphinx's autodoc extension, but their output seems pretty
comparable.

Darren

···

On Tuesday 25 March 2008 07:07:33 pm Gael Varoquaux wrote:

On Tue, Mar 25, 2008 at 06:04:41PM -0500, bryce hendrix wrote:
> How stable is the API? We (Enthought) use endo, a custom tool build on
> top of docutils, to generate our docs currently. We have talked about
> changing tools in the past, but the need to extend the tools to
> understand Traits has held us back.

Sphinx is not automated API documentation, like Endo or Epidoc. It is for
manual writing of documentation. It does not compete with Endo or Epidoc,
but complements them by taking a set of rst files and compiling both a
set of searchable web pages, and an indexed pdf for print.

I am planning on starting to overhaul the documentation using Sphinx next
week. I have been experimenting with Sphinx to create some documentation for
a project at work (http://dale.chess.cornell.edu/~darren/xpaxs/index.xml and
http://dale.chess.cornell.edu/~darren/temp/XPaXS.pdf). I'm really impressed
with Sphinx, I think it will allow us to unify the matplotlib docstrings,
webpage and the pdf copies of the users guide / developers guide / API
reference.

In order to integrate all the doumentation together, it would be best if I
could convert the mpl docstrings to ReST. This would be quite a big project,
and I don't want to commit us before we have a chance to evaluate the
results, so I guess a documentation branch would be appropriate. Could
someone help guide me through the process of creating a new branch and
pulling in some of the older doc sources? Aside from Johns recent post about
using svnmerge, is there anything else I should keep in mind while trying to
keep the branch in sync with the trunk?

Thanks,
Darren

I am planning on starting to overhaul the documentation using Sphinx next
week. I have been experimenting with Sphinx to create some documentation for
a project at work (http://dale.chess.cornell.edu/~darren/xpaxs/index.xml and
http://dale.chess.cornell.edu/~darren/temp/XPaXS.pdf). I'm really impressed
with Sphinx, I think it will allow us to unify the matplotlib docstrings,
webpage and the pdf copies of the users guide / developers guide / API
reference.

These look nice.

In order to integrate all the doumentation together, it would be best if I
could convert the mpl docstrings to ReST. This would be quite a big project,
and I don't want to commit us before we have a chance to evaluate the
results, so I guess a documentation branch would be appropriate. Could
someone help guide me through the process of creating a new branch and
pulling in some of the older doc sources? Aside from Johns recent post about
using svnmerge, is there anything else I should keep in mind while trying to
keep the branch in sync with the trunk?

I'd rather avoid another branch if possible. I think it would be
easier to just do a single module first and post it to the list, and
then we can evaluate it. If we like it, then we can just keep doing a
module at a time in the trunk.

···

On Thu, May 22, 2008 at 8:15 AM, Darren Dale <darren.dale@...143...> wrote:

Just something to keep in mind: many of the docstrings are pieced together at import time (to avoid rewriting descriptions of common parameters). Any tool that extracts docstrings by parsing Python rather than importing Python may choke on that approach.

Cheers,
Mike

You're right, that sounds easier. Here's a taste, it has a bit taken from the
users guide, I marked up the CODING_GUIDE, and I used the autodoc extension
to document the API of texmanager and dviread:

http://dale.chess.cornell.edu/~darren/temp/matplotlib/index.xml
http://dale.chess.cornell.edu/~darren/temp/matplotlib/Matplotlib.pdf

For comparison, here is the texmanager API done with Sphinx:
http://dale.chess.cornell.edu/~darren/temp/matplotlib/mpl_api.xml#module-matplotlib.texmanager
and here is the existing API documentation:
http://matplotlib.sourceforge.net/matplotlib.texmanager.html

Darren

···

On Thursday 22 May 2008 09:56:04 am John Hunter wrote:

On Thu, May 22, 2008 at 8:15 AM, Darren Dale <darren.dale@...143...> wrote:
> I am planning on starting to overhaul the documentation using Sphinx next
> week. I have been experimenting with Sphinx to create some documentation
> for a project at work
> (http://dale.chess.cornell.edu/~darren/xpaxs/index.xml and
> http://dale.chess.cornell.edu/~darren/temp/XPaXS.pdf). I'm really
> impressed with Sphinx, I think it will allow us to unify the matplotlib
> docstrings, webpage and the pdf copies of the users guide / developers
> guide / API reference.

These look nice.

> In order to integrate all the doumentation together, it would be best if
> I could convert the mpl docstrings to ReST. This would be quite a big
> project, and I don't want to commit us before we have a chance to
> evaluate the results, so I guess a documentation branch would be
> appropriate. Could someone help guide me through the process of creating
> a new branch and pulling in some of the older doc sources? Aside from
> Johns recent post about using svnmerge, is there anything else I should
> keep in mind while trying to keep the branch in sync with the trunk?

I'd rather avoid another branch if possible. I think it would be
easier to just do a single module first and post it to the list, and
then we can evaluate it. If we like it, then we can just keep doing a
module at a time in the trunk.

Yes, that might have been a big problem, but it looks like Sphinx does the
right thing. axes.Axes.plot includes the following in its docstring:

        The kwargs are Line2D properties:
        %(Line2D)s

And the rendering at
http://dale.chess.cornell.edu/~darren/temp/matplotlib/mpl_api.xml#matplotlib-axes
is what we would want (although the formatting in html is missing some
newlines):

The kwargs are Line2D properties:

    alpha: float
    animated: [True | False]
    antialiased or aa: [True | False]
    axes: unknown
    clip_box: a matplotlib.transform.Bbox instance
    clip_on: [True | False]
    clip_path: a Path instance and a Transform instance, a Patch
    color or c: any matplotlib color
    contains: unknown
    dash_capstyle: [‘butt’ | ‘round’ | ‘projecting’]
    dash_joinstyle: [‘miter’ | ‘round’ | ‘bevel’]
    dashes: sequence of on/off ink in points
    data: (np.array xdata, np.array ydata)
    figure: a matplotlib.figure.Figure instance
    label: any string
    linestyle or ls:
[ ‘-‘ | ‘–’ | ‘-.’ | ‘:’ | ‘steps’ | ‘steps-pre’ | ‘steps-mid’ | ‘steps-post’ | ‘None’ | ‘ ‘ | ‘’ ]
    linewidth or lw: float value in points
    lod: [True | False]
    marker: [ ‘+’ | ‘,’ | ‘.’ | ‘1’ | ‘2’ | ‘3’ | ‘4’
    markeredgecolor or mec: any matplotlib color
    markeredgewidth or mew: float value in points
    markerfacecolor or mfc: any matplotlib color
    markersize or ms: float
    picker: unknown
    pickradius: unknown
    solid_capstyle: [‘butt’ | ‘round’ | ‘projecting’]
    solid_joinstyle: [‘miter’ | ‘round’ | ‘bevel’]
    transform: a matplotlib.transforms.Transform instance
    visible: [True | False]
    xdata: np.array
    ydata: np.array
    zorder: any number

···

On Thursday 22 May 2008 01:23:53 pm Michael Droettboom wrote:

Just something to keep in mind: many of the docstrings are pieced
together at import time (to avoid rewriting descriptions of common
parameters). Any tool that extracts docstrings by parsing Python rather
than importing Python may choke on that approach.

How do you envision putting this together? Will each of these
documents (eg CODING_GUIDE) live as separate rest files and are then
included in one doc? I don't think we will want to have one master
PDF for the user's guide, developer's guide and api docs (the
autogenerated api docs at http://matplotlib.sf.net/api.pdf are 560
pages along). Did you do any rest conversion of the texmanager and
dviread, or did autodoc do everything? I'd like to get a feel for
what the rest markup of the docstrings will look like.

In any case, this is exciting, since I am eager to have a nice rest
based doc system. You might want to look at incorporating the three
rest docs in the doc subdir: artist_api_tut.txt,
event_handling_tut.txt and devel/add_new_projection.rst since these
are already done. I guess we also need to standardize on rst vs txt
extensions. I think txt is friendlier to windoze users, and I have my
emacs to use rest mode for *.txt
(require 'rst)
(autoload 'rst-mode "rst-mode" "mode for editing reStructuredText documents" t)
(setq auto-mode-alist
       (append '(
     ("\\.txt$" . rst-mode)
     ("\\.rst$" . rst-mode)
     ("\\.rest$" . rst-mode)) auto-mode-alist))

As you as you can, commit a working directory for the doc build and
I'll help with some of the conversion of the existing docs to rest.
We can split up the user's guide chapters, etc...

JDH

···

On Thu, May 22, 2008 at 12:48 PM, Darren Dale <darren.dale@...143...> wrote:

You're right, that sounds easier. Here's a taste, it has a bit taken from the
users guide, I marked up the CODING_GUIDE, and I used the autodoc extension
to document the API of texmanager and dviread:

> You're right, that sounds easier. Here's a taste, it has a bit taken from
> the users guide, I marked up the CODING_GUIDE, and I used the autodoc
> extension to document the API of texmanager and dviread:

How do you envision putting this together? Will each of these
documents (eg CODING_GUIDE) live as separate rest files and are then
included in one doc?

We have a lot of flexibility here. I prefer to pull from a few smaller
documents using rest include statements or table of contents directives.
Ipython, on the other hand, has the whole guide included in one file.

I don't think we will want to have one master
PDF for the user's guide, developer's guide and api docs (the
autogenerated api docs at http://matplotlib.sf.net/api.pdf are 560
pages along).

Ok. It is easy enough to break them up into separate documents. I'll work on
it this afternoon. Should we have a separate developers guide, or could it be
included in the users guide?

Did you do any rest conversion of the texmanager and
dviread, or did autodoc do everything?

I had to do some minor modifications to make sure the docstrings were valid
rest: proper indentation is important, and * is used to indicate emphasis, so
any references to *args or **kwags had to be changed to ``*args`` and
``**kwargs`` (I didnt like \*\*kwargs, its too intrusive for reading the
plain text).

I'd like to get a feel for
what the rest markup of the docstrings will look like.

Here is the docstring for the texmanager module:

"""
This module supports embedded TeX expressions in matplotlib via dvipng
and dvips for the raster and postscript backends. The tex and
dvipng/dvips information is cached in ~/.matplotlib/tex.cache for reuse
between
sessions

Requirements:

* latex
* \*Agg backends: dvipng
* PS backend: latex w/ psfrag, dvips, and Ghostscript 8.51
  (older versions do not work properly)

Backends:

* \*Agg
* PS
* PDF

For raster output, you can get RGBA numpy arrays from TeX expressions
as follows::

  texmanager = TexManager()
  s = '\\TeX\\ is Number \\\\displaystyle\\\\sum\_\{n=1\}^\\\\infty\\\\frac\{\-e^\{i\\pi\}\} \{2^n\}!'
  Z = self.texmanager.get_rgba(s, size=12, dpi=80, rgb=(1,0,0))

To enable tex rendering of all text in your matplotlib figure, set
text.usetex in your matplotlibrc file (http://matplotlib.sf.net/matplotlibrc)
or include these two lines in your script::

  from matplotlib import rc
  rc('text', usetex=True)

"""

I am really amazed at how much can be done with so little. For example, near
the end of that docstring, two colons followed by a blank line and then an
indented block indicates a block of source code.

In any case, this is exciting, since I am eager to have a nice rest
based doc system. You might want to look at incorporating the three
rest docs in the doc subdir: artist_api_tut.txt,
event_handling_tut.txt and devel/add_new_projection.rst since these
are already done.

Ok, they are included now:
http://dale.chess.cornell.edu/~darren/temp/matplotlib/index.xml
and http://dale.chess.cornell.edu/~darren/temp/matplotlib/Matplotlib.pdf

I guess we also need to standardize on rst vs txt
extensions. I think txt is friendlier to windoze users, and I have my
emacs to use rest mode for *.txt
(require 'rst)
(autoload 'rst-mode "rst-mode" "mode for editing reStructuredText
documents" t) (setq auto-mode-alist
       (append '(
     ("\\.txt$" . rst-mode)
     ("\\.rst$" . rst-mode)
     ("\\.rest$" . rst-mode)) auto-mode-alist))

I prefer .rst, it makes it clear that there is a specific markup, which could
be overlooked by the uninitiated contributer. But I don't have a strong
opinion.

As you as you can, commit a working directory for the doc build and
I'll help with some of the conversion of the existing docs to rest.
We can split up the user's guide chapters, etc...

Sounds good. I'll work on splitting the docs and make the commit this
afternoon. Before I commit, could we have a ruling on whether the developers
guide should be included in the users guide, and should we use .rst or .txt
extensions? (sphinx wants one or the other.)

Darren

···

On Thursday 22 May 2008 02:05:14 pm John Hunter wrote:

On Thu, May 22, 2008 at 12:48 PM, Darren Dale <darren.dale@...143...> wrote:

We have a lot of flexibility here. I prefer to pull from a few smaller
documents using rest include statements or table of contents directives.
Ipython, on the other hand, has the whole guide included in one file.

I would like to go with smaller files if it is possible, since it
would be nice to have little simple text documents (coding_guide.txt,
migration.txt, artist_tutorial.txt) that people can read in their
editors which are assembled into the docs for PDF and HTML

I don't think we will want to have one master
PDF for the user's guide, developer's guide and api docs (the
autogenerated api docs at http://matplotlib.sf.net/api.pdf are 560
pages along).

Ok. It is easy enough to break them up into separate documents. I'll work on
it this afternoon. Should we have a separate developers guide, or could it be
included in the users guide?

Since the developers stuff is minimal now, it can be included. If and
when it ever grows to a substantial size, we can break it out.

Here is the docstring for the texmanager module:

great -- that is very human readable in the src code, which is what I want.

Ok, they are included now:
http://dale.chess.cornell.edu/~darren/temp/matplotlib/index.xml
and http://dale.chess.cornell.edu/~darren/temp/matplotlib/Matplotlib.pdf

Het, now we are getting somewhere! We may need to work on the toc a
bit, since we should see one header for "The Artist Tutorial" and then
all the subheaders indented relative to that, but that should be easy
enough. There is also some code formatting problem in the PDF -- see
the 'import numpy as np" in the "Style Guide" section of the PDF.

JDH

···

On Thu, May 22, 2008 at 1:44 PM, Darren Dale <darren.dale@...143...> wrote:

I just committed the beginnings of a Sphinx-based documentation to svn. It
includes a section explaining how to get up and running with sphinx, its
*really easy*:
http://dale.chess.cornell.edu/~darren/temp/matplotlib/Users_Guide/documenting_mpl.xml

Here is the same documentation in plain text:

···

**********************
Documenting Matplotlib
**********************

The documentation for matplotlib is generated from ReStructured Text
using the Sphinx_ documentation generation tool. Sphinx-0.4 or later
is required to generate xml files to render mathematical expressions
with mathml. Currently this means we need to install from the svn
repository by doing::

  svn co http://svn.python.org/projects/doctools/trunk sphinx
  cd sphinx
  python setup.py install

.. _Sphinx: http://sphinx.pocoo.org/

The documentation sources are found in the doc/ directory in the trunk.
To build the users guid in html format, cd into doc/users_guide and do::

  python make.py html

you can also pass a ``latex`` flag to make.py to build a pdf, or pass no
arguments to build everything. The same procedure can be followed for
the sources in doc/api_reference.

The actual ReStructured Text files are kept in doc/users_guide/source
and doc/api_reference/source. The main entry point is index.txt.
Additional files can be added by including their base file name
(dropping the .txt extension) in the table of contents. It is also
possible to include other documents through the use of an include
statement. For example, in the Developers Guide, index.txt lists
coding_guide, which automatically inserts coding_guide.txt.
coding_guide.txt is just a placeholder, it contains one line only to
gets its contents from the CODING_GUIDE file in the trunk:
``.. include:: ../../CODING_GUIDE``.

The output produced by Sphinx can be configured by editing the conf.py
files located in the documentation source directories.

The Sphinx website contains plenty of documentation_ concerning ReST
markup and working with Sphinx in general.

.. _documentation: http://sphinx.pocoo.org/contents.html

Darren,
I think this is a GREAT idea. I've been trying to free up some resources to
work on a better MPL user's guide for our users this year. If I can swing
it, perhaps we can help contribute some sections.

Given that we use the units system extensively, we'd probably have some
sections that are pure MPL and a lot of sections that use our custom time
and unit types. It might be nice if there were hooks where we could build
our own local docs in with the standard docs. I'm guess that would be
fairly easy...

Ted

···

-----Original Message-----
From: matplotlib-devel-bounces@lists.sourceforge.net
[mailto:matplotlib-devel-bounces@lists.sourceforge.net] On Behalf Of
Darren Dale
Sent: Thursday, May 22, 2008 6:15 AM
To: matplotlib-devel@lists.sourceforge.net
Subject: Re: [matplotlib-devel] future of mpl documentation

I am planning on starting to overhaul the documentation using Sphinx
next
week. I have been experimenting with Sphinx to create some
documentation for
a project at work
(http://dale.chess.cornell.edu/~darren/xpaxs/index.xml and
http://dale.chess.cornell.edu/~darren/temp/XPaXS.pdf). I'm really
impressed
with Sphinx, I think it will allow us to unify the matplotlib
docstrings,
webpage and the pdf copies of the users guide / developers guide / API
reference.

In order to integrate all the doumentation together, it would be best
if I
could convert the mpl docstrings to ReST. This would be quite a big
project,
and I don't want to commit us before we have a chance to evaluate the
results, so I guess a documentation branch would be appropriate. Could
someone help guide me through the process of creating a new branch and
pulling in some of the older doc sources? Aside from Johns recent post
about
using svnmerge, is there anything else I should keep in mind while
trying to
keep the branch in sync with the trunk?

Thanks,
Darren

-----------------------------------------------------------------------
--
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2008.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
matplotlib-devel List Signup and Options
Checked by AVG.
Version: 8.0.100 / Virus Database: 269.24.0/1460 - Release Date:
5/22/2008 7:06 AM

Darren, thanks a lot for getting this going. I think this is going to
push the documentation effort forward significantly. It certainly has
got me hot and bothered to write some docs!

A couple of organizational things:

  - flat is better than nested. I think the basic organization is
good but I want to balance the cleanliness of the developer/build view
with the plain text user view. To that end, perhaps having a "source"
subdir in doc/users_guide is overkill. Should we have all the *.txt
file live next to the make.py file? I want users browsing the
doc/users_guide dir to see all the stuff they need (artist tut, event
handling tut, etc) withought getting confused by the "build" or
"figures" or "data" subdirs living beside a "source" subdir). It
seems that it would not significantly add to the clutter to have all
the txt files at a higher level. We *could* go one step further, and
have all the *.txt files live directly in the "doc" dir itself, and
the various subdirs like "users_guide" or "api_reference" or "jpl" or
whatever could reference the parent directory for the includes. I'm
not sure this is right, but it is consistent with the view that we
have a lot of modular, somewhat freestanding, human readable, plain
text rest files that can be combined into whatever package one wants
via include files (eg the JPL could make their own custom docs from
the pool) and it would work like the (old) pylab examples dir (one
stop shopping for examples with ls and grep). Admittedly, the
examples organization eventually became unwieldy, which is why I
reorganized it in the trunk, but that is a good problem to have and it
took years to get there. Your call, but just some food for thought.

  - I think we should be mostly consistent with whether we use
underscores to separate english words. So we have artist_api_tut .txt
but userguide.txt. For the sake of a foolish consistency, how about
user_guide.txt too?

Great work!
JDH

···

On Thu, May 22, 2008 at 4:59 PM, Darren Dale <darren.dale@...143...> wrote:

I just committed the beginnings of a Sphinx-based documentation to svn. It
includes a section explaining how to get up and running with sphinx, its
*really easy*:

> I just committed the beginnings of a Sphinx-based documentation to svn.
> It includes a section explaining how to get up and running with sphinx,
> its *really easy*:

Darren, thanks a lot for getting this going. I think this is going to
push the documentation effort forward significantly. It certainly has
got me hot and bothered to write some docs!

A couple of organizational things:

  - flat is better than nested. I think the basic organization is
good but I want to balance the cleanliness of the developer/build view
with the plain text user view. To that end, perhaps having a "source"
subdir in doc/users_guide is overkill. Should we have all the *.txt
file live next to the make.py file? I want users browsing the
doc/users_guide dir to see all the stuff they need (artist tut, event
handling tut, etc) withought getting confused by the "build" or
"figures" or "data" subdirs living beside a "source" subdir). It
seems that it would not significantly add to the clutter to have all
the txt files at a higher level.

I just removed the source directories, like you suggested. You might get
errors the next time you run make.py, just delete the build directories and
it should correct itself.

We *could* go one step further, and
have all the *.txt files live directly in the "doc" dir itself, and
the various subdirs like "users_guide" or "api_reference" or "jpl" or
whatever could reference the parent directory for the includes. I'm
not sure this is right, but it is consistent with the view that we
have a lot of modular, somewhat freestanding, human readable, plain
text rest files that can be combined into whatever package one wants
via include files (eg the JPL could make their own custom docs from
the pool) and it would work like the (old) pylab examples dir (one
stop shopping for examples with ls and grep). Admittedly, the
examples organization eventually became unwieldy, which is why I
reorganized it in the trunk, but that is a good problem to have and it
took years to get there. Your call, but just some food for thought.

This way could work, but I think it would quickly become unwieldy. Lets stick
with this for now, we can always reorganize later if we feel strongly about
it. This way, JPL or others can still reference docs in their sister
directories.

  - I think we should be mostly consistent with whether we use
underscores to separate english words. So we have artist_api_tut .txt
but userguide.txt. For the sake of a foolish consistency, how about
user_guide.txt too?

This is improved in the trunk.

Darren

···

On Thursday 22 May 2008 10:10:13 pm John Hunter wrote:

On Thu, May 22, 2008 at 4:59 PM, Darren Dale <darren.dale@...143...> wrote: