Darren has kick started a documentation effort in sphinx (which
resides in the doc subdir of the trunk) that is proving quite
successful. sphinx is ReST based, and is pretty easy to jump into.
As I understand it, Darren will have some time over the summer to
contribute to the effort (porting the existing docstrings in the API
documentation and the existing user's guide) but there is a lot to be
done. mpl has decent docs, certainly not great docs, and I'd like to
capitalize on the inertia Darren has created and try and strong arm
more of you into contributing to this effort. There is plenty to be
done, and even if you are no mpl expert there is lot you can
contribute.
I have organized a document in the developer's section
(doc/devel/outline.rst in the mpl src tree) listing units I think
would be good additions to the docs, suggesting authors in some cases
where I know someone is particularly well qualified, setting a status
field ("no author", "has author", "submitted", "complete") etc....
There are lots of ? symbols, which means either that we have no
candidate, or that my designee has not accepted the designation. Eg,
I may have nominated Eric Firing for a section, but he hasn't yet
agreed to do it, so I put a ? by his name. When he agrees to do it,
he can remove the ? by his name in svn. Importantly, every section
has an editor, and these fields are currently mostly populated by ?.
The editor responsibility is pretty light: read the chapter, check it
for style and correctness, and sign off on it.
By no means do we need to go this route -- we can continue to
contribute as we can, which has worked well in the rest of the mpl
code base and is currently working well for the new docs. If you find
this excessively bureaucratic or onerous, I'm happy to shelve the
approach. This is mostly an attempt to get more people involved in
the documentation effort by making a pubic show of the work that we
needs to be done, with bite size pieces that pepole can sign on for,
and it is less of an effort to get a formal review process in place.
But docs are an area where an "editor" can make a significant
contribution with a fairly minimal effort, so I think having a review
is a good addition. I stress in the outline.rst doc::
It is probably easiest to be an editor. Once you have signed up to be
an editor, if you have an author, pester the author for a submission
every so often. If you don't have an author, find one, and then pester
them! Your only two responsibilities are getting your author to
produce and checking their work, so don't be shy. You *do not* need
to be an expert in the subject you are editing -- you should know
something about it and be willing to read, test, give feedback and
pester!
Included below is the outline.rst doc from the devel documentation.
Since a lot of email readers mangle the spacing, you can also consult
the mpl src in docs/devel/outline.rst or the html rendered version at
http://matplotlib.sourceforge.net/mpldocs/devel/outline.html or the
src online at http://matplotlib.sourceforge.net/mpldocs/_sources/devel/outline.txt
.
Those of you who are developers can jump in and edit the outline doc,
assigning yourself, removing yourself, updating the status, etc...
Those of you who don't have commit rights but want to participate,
just respond here with author or editor positions you want and/or
submit a patch against the file. Also, I expect there are many
glaring holes in the topic list so do not be shy in making additions,
deletions or revisions.
JDH
outline.rst:
.. _outline:
···
************
Docs outline
************
Proposed chapters for the docs, who has responsibility for them, and
who reviews them. The "unit" doesn't have to be a full chapter
(though in some cases it will be), it may be a chapter or a section in
a chapter.
=============================== ==================== ===========
User's guide unit Author Status Reviewer
=============================== ==================== ===========
contouring Eric ? no author Perry ?
quiver plots Eric ? no author ?
quadmesh ? no author ?
images ? no author ?
histograms Manuel ? no author
Erik Tollerud ?
bar / errorbar ? no author ?
x-y plots ? no author ?
time series plots ? no author ?
date plots John has author ?
working with data John has author ?
custom ticking ? no author ?
masked data Eric ? no author ?
text ? no author ?
patches ? no author ?
legends ? no author ?
animation John has author ?
collections ? no author ?
mathtext Michael ? submitted John
fonts et al Michael ? no author ?
pyplot tut John submitted Eric ?
usetex Darren ? no author ?
configuration Darren ? preliminary ?
colormapping Perry ? no author Eric ?
win32 install Charlie ? no author ?
os x install Charlie ? no author ?
linux install ? no author ?
artist api John submitted ?
event handling John submitted ?
navigation John submitted ?
interactive usage ? no author ?
widgets ? no author ?
ui - gtk ? no author ?
ui - wx ? no author ?
ui - tk ? no author ?
ui - qt Darren ? no author ?
backend - pdf Jouni ? no author ?
backend - ps Darren ? no author ?
backend - svg ? no author ?
backend - agg ? no author ?
backend - cairo ? no author ?
=============================== ==================== ===========
Here is the ouline for the dev guide, much less fleshed out
=============================== ==================== ===========
Developer's guide unit Author Status Reviewer
=============================== ==================== ===========
the renderer John has author Michael ?
the canvas John has author ?
the artist John has author ?
transforms Michael submitted John
documenting mpl Darren submitted ?
coding guide John submitted ?
and_much_more ? ? ?
=============================== ==================== ===========
And we might want to do a similar table for the FAQ, but that may also
be overkill...
If you agree to author a unit, remove the question mark by your name
(or add your name if there is no candidate), and change the status to
"has author". Once you have completed draft and checked it in, you
can change the status to "submitted" and try to find a reviewer if you
don't have one. The reviewer should read your chapter, test it for
correctness (eg try your examples) and change the status to "complete"
when done.
You are free to lift and convert as much material from the web site or
the existing latex user's guide as you see fit. The more the better.
The UI chapters should give an example or two of using mpl with your
GUI and any relevant info, such as version, installation, config,
etc... The backend chapters should cover backend specific
configuration (eg PS only options), what features are missing, etc...
Please feel free to add units, volunteer to review or author a
chapter, etc...
It is probably easiest to be an editor. Once you have signed up to be
an editor, if you have an author pester the author for a submission
every so often. If you don't have an author, find one, and then pester
them! Your only two responsibilities are getting your author to
produce and checking their work, so don't be shy. You *do not* need
to be an expert in the subject you are editing -- you should know
something about it and be willing to read, test, give feedback and
pester!