Hello,
My first message in the list. I would like to mention a few things about the matplotlib PDF document.
Firstly, the download link for the pdf document (@ http://matplotlib.sourceforge.net/contents.html) is for release 0.98.5.1, compiled on December 17, instead of 0.98.5.2, on Dec-18.
Next, is there a way to get functions separately listed under each bookmark listing in the pdf file? For example if I go IV Matplotlib API section from the bookmarks menu and click the matplotlib.pyplot seb-menu I would like to see the function names listed. In addition to module indexing (where keywords highlighted back to original names) this would be a nice feature to add the pdf documentation.
If this needs a manual configuration, I am volunteering to spend time to add this functionality.
Regards,
Gökhan SEVER
Gökhan SEVER wrote:
Hello,
My first message in the list. I would like to mention a few things about the matplotlib PDF document.
Firstly, the download link for the pdf document (@ http://matplotlib.sourceforge.net/contents.html) is for release 0.98.5.1, compiled on December 17, instead of 0.98.5.2, on Dec-18.
Thanks. I don't recall the current policy under which documentation is being pushed to the site, so I'll leave that for others to address.
Next, is there a way to get functions separately listed under each bookmark listing in the pdf file? For example if I go IV Matplotlib API section from the bookmarks menu and click the matplotlib.pyplot seb-menu I would like to see the function names listed. In addition to module indexing (where keywords highlighted back to original names) this would be a nice feature to add the pdf documentation.
This sounds like something to be added/fixed within the documentation system we use -- Sphinx. If you want to tackle this yourself, I would head over there and read some documentation and mailing lists and see if it's been done -- otherwise pursue what it might take to make it work. We would definitely welcome this change.
Mike
···
--
Michael Droettboom
Science Software Branch
Operations and Engineering Division
Space Telescope Science Institute
Operated by AURA for NASA
I am willing to add this functionality to the documentation. Unfortunately, I have still not been able to figure out how sphinx inserting functions or classes in order and how the module index is being created.
Once I found my way I will try to come up with a generic way for this. Maybe someone can give some more insight to the subject?
Thanks,
Gökhan
Hello,
About two months ago I was asking how to implement the following
functionality for matplotlib documentation. Well today I figured it
out 
I was busy with some other school work not been thinking for
over twom months 
"Is there a way to get functions separately listed under each bookmark
listing in the pdf file? For example if I go IV Matplotlib API section
from the bookmarks menu and click the matplotlib.pyplot seb-menu I
would like to see the function names listed. In addition to module
indexing (where keywords highlighted back to original names) this
would be a nice feature to add the pdf documentation."
Enough said, here is what I did. (Thanks to Georg Brandl of Sphinx)
(As of now the latest svn checkout 0.98.6svn_rev__7068 although
__revision__ says: 6887, and with Sphinx 0.6.1)
I have modified the pyplot_api.rst as follows:
.. automodule:: matplotlib.pyplot
:undoc-members:
:show-inheritance:
acorr
···
=====
.. autofunction:: acorr
annotate
.. autofunction:: annotate
and other 121 manual entries. (The new PDF file is 12 pages more than
original file.) While I was adding the function names I thought of
myself that these could be done via a little program. I mean before
Sphinx visit --in this case pyplot.py function names might read into a
list and following this an appropriate rst file could be created (and
this is also apply for the other api documentation as well). Or
another way, these could be added to Sphinx as a feature, that is to
say read function names and read docstrings, create figures etc.. and
make a subsection for each item via a special syntax.
The first method eliminates having a pre-written pyplot_api.rst file
since this could be created via a short python script.
I would like discuss these point before start working on other api
functions and classes. Also need some explanation about them, since
pyplot is composed of functions but some other api's are mixed with
classes and functions.
Please, contact me of the list so I can send the modified pyploy_rst.api.
Gökhan
Hey Gökhan – thanks for working on this. We are very happy to have documentation contributions. I don’t feel strongly about how the pyplot rst file is generated, whether by extending Sphinx, using a script, or simply hand editing it. I’m actually incline toward the latter, because it would probably be nice to have some simple description in the section header, eg::
acorr - autocorrelation plots
···
On Wed, Apr 29, 2009 at 2:55 AM, Gökhan SEVER <gokhansever@…287…> wrote:
I would like discuss these point before start working on other api
functions and classes. Also need some explanation about them, since
pyplot is composed of functions but some other api’s are mixed with
classes and functions.
Please, contact me of the list so I can send the modified pyploy_rst.api.
=====================
as we do on the main page. Part of the sphinx philosophy is that “hand edited” documentation cannot be fully replaced by autogenerated documentaiton, and this may be a reasonable place to do some hand editing.
If you go this route, update the pyplot module, the developer’s guide and the boilerplate.py script (it lives besides setup.py and is a script to generate part of pyplot) so that when developers add a new function to pyplot they know to update the api docs as well.
You may want to move further discussion over to the developers list. Any changes you want to make should be posted as an svn diff to the developers list. If you don’t get immediate attention, also post it as a patch to the sourceforge site, and reply to the developers list with a link to the patch – see
http://matplotlib.sourceforge.net/faq/howto_faq.html#contributing-howto
Thanks!
JDH