Revision: 5548
http://matplotlib.svn.sourceforge.net/matplotlib/?rev=5548&view=rev
Author: dsdale
Date: 2008-06-15 08:29:57 -0700 (Sun, 15 Jun 2008)
Log Message:
-----------
Expanded on documentation guidelines
Modified Paths:
--------------
trunk/matplotlib/doc/devel/documenting_mpl.rst
trunk/matplotlib/doc/glossary/index.rst
Modified: trunk/matplotlib/doc/devel/documenting_mpl.rst
===================================================================
--- trunk/matplotlib/doc/devel/documenting_mpl.rst 2008-06-15 12:08:13 UTC
(rev 5547)
+++ trunk/matplotlib/doc/devel/documenting_mpl.rst 2008-06-15 15:29:57 UTC
(rev 5548)
@@ -33,6 +33,7 @@
The output produced by Sphinx can be configured by editing the `conf.py`
file located in the `doc/`.
+
Organization of matplotlib's documentation
==========================================
@@ -50,6 +51,7 @@
.. include:: ../../TODO
+
Formatting
==========
@@ -61,6 +63,20 @@
other semantic markup. For example, when referring to external files, use the
``:file:`` directive.
+* Function arguments and keywords should be referred to using the *emphasis*
+ role. This will keep matplotlib's documentation consistant with Python's
+ documentation::
+
+ Here is a description of *argument*
+
+ Please do not use the `default role`::
+
+ Please do not describe `argument` like this.
+
+ nor the ``literal`` role::
+
+ Please do not describe ``argument`` like this.
+
* Sphinx does not support tables with column- or row-spanning cells for
latex output. Such tables can not be used when documenting matplotlib.
@@ -92,10 +108,96 @@
In [69]: lines = plot([1,2,3])
+* Footnotes [#]_ can be added using ``[#]_``, followed later by::
+
+ .. rubric:: Footnotes
+
+ .. [#]
+
+ .. rubric:: Footnotes
+
+ .. [#] For example.
+
+* Use the *note* and *warning* directives, sparingly, to draw attention to
+ important comments::
+
+ .. note::
+ Here is a note
+
+ yields:
+
+ .. note::
+ here is a note
+
+ also:
+
+ .. warning::
+ here is a warning
+
+* Use the *deprecated* directive when appropriate::
+
+ .. deprecated:: 0.98
+ This feature is obsolete, use something else.
+
+ yields:
+
+ .. deprecated:: 0.98
+ This feature is obsolete, use something else.
+
+* Use the *versionadded* and *versionchanged* directives, which have similar
+ syntax to the *deprecated* role::
+
+ .. versionadded:: 0.98
+ The transforms have been completely revamped.
+
+ .. versionadded:: 0.98
+ The transforms have been completely revamped.
+
+* Use the *seealso* directive, for example::
+
+ .. seealso::
+
+ Using ReST :ref:`emacs-helpers`:
+ One example
+
+ A bit about :ref:`referring-to-mpl-docs`:
+ One more
+
+ yields:
+
+ .. seealso::
+
+ Using ResT :ref:`emacs-helpers`:
+ One example
+
+ A bit about :ref:`referring-to-mpl-docs`:
+ One more
+
+* Please keep the :ref:`glossary` in mind when writing documentation. You can
+ create a references to a term in the glossary with the ``:term:`` role.
+
+* The autodoc extension will handle index entries for the API, but additional
+ entries in the index_ need to be explicitly added.
+
.. _documentation: http://sphinx.pocoo.org/contents.html
.. _`inline markup`: http://sphinx.pocoo.org/markup/inline.html
+.. _index: http://sphinx.pocoo.org/markup/para.html#index-generating-markup
+Docstrings
+----------
+In addition to the aforementioned formatting suggestions:
+
+* Please limit the text width of docstrings to 70 characters.
+
+* Keyword arguments should be described using a definition list.
+
+ .. note::
+ matplotlib makes extensive use of keyword arguments as pass-through
+ arguments, there are a many cases where a table is used in place of a
+ definition list for autogenerated sections of docstrings.
+
+
Figures
=======
@@ -139,7 +241,6 @@
:include-source
-
.. _referring-to-mpl-docs:
Referring to mpl documents
@@ -166,8 +267,6 @@
.. literalinclude:: ../mpl_data/matplotlibrc
-
-
.. _internal-section-refs:
Internal section references
@@ -196,8 +295,8 @@
In addition, since underscores are widely used by Sphinx itself, let's prefer
hyphens to separate words.
-.. _emacs-helpers:
+
Section names, etc
==================
@@ -205,6 +304,9 @@
section titles, eg ``Possible hangups`` rather than ``Possible
Hangups``
+
+.. _emacs-helpers:
+
Emacs helpers
=============
Modified: trunk/matplotlib/doc/glossary/index.rst
===================================================================
--- trunk/matplotlib/doc/glossary/index.rst 2008-06-15 12:08:13 UTC (rev
5547)
+++ trunk/matplotlib/doc/glossary/index.rst 2008-06-15 15:29:57 UTC (rev
5548)
@@ -1,6 +1,9 @@
-########
+
+.. _glossary:
+
+********
Glossary
-########
+********
.. glossary::
This was sent by the SourceForge.net collaborative development platform, the
world's largest Open Source development site.
-------------------------------------------------------------------------
Check out the new SourceForge.net Marketplace.
It's the best place to buy or sell services for
just about anything Open Source.
http://sourceforge.net/services/buy/index.php
_______________________________________________
Matplotlib-checkins mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/matplotlib-checkins
