Expanded on documentation guidelines

ddale · ddale · commit e8f41a1f0c01 · 2008-06-15T15:29:57.000Z
svn path=/trunk/matplotlib/; revision=5548
diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
@@ -33,6 +33,7 @@ arguments to build everything.
 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 @@ statement, such as::
 
   .. include:: ../../TODO
 
+  
 Formatting
 ==========
 
@@ -61,6 +63,20 @@ working with Sphinx in general. Here are a few additional things to keep in mind
   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,9 +108,95 @@ working with Sphinx in general. Here are a few additional things to keep in mind
 
     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 @@ taken, these figures can be included in the usual way::
       :include-source
 
 
-
 .. _referring-to-mpl-docs:
 
 Referring to mpl documents
@@ -166,8 +267,6 @@ directory, I use the symlink directory.  For example, from
    .. literalinclude:: ../mpl_data/matplotlibrc
 
 
-
-
 .. _internal-section-refs:
 
 Internal section references
@@ -196,7 +295,7 @@ is better than::
 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 @@ For everything but top level chapters, please use ``Upper lower`` for
 section titles, eg ``Possible hangups`` rather than ``Possible
 Hangups``
 
+
+.. _emacs-helpers:
+
 Emacs helpers
 =============
 
diff --git a/doc/glossary/index.rst b/doc/glossary/index.rst
@@ -1,6 +1,9 @@
-########
+
+.. _glossary:
+
+********
 Glossary
-########
+********
 
 .. glossary::
 
