SF.net SVN: matplotlib: [5548] trunk/matplotlib/doc

[<ds...@us...>]

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.