some more doc updates

jdh2358 · jdh2358 · commit 1441d2ba93dc · 2008-06-02T21:01:47.000Z
svn path=/trunk/matplotlib/; revision=5367
diff --git a/doc/devel/add_new_projection.rst b/doc/devel/add_new_projection.rst
@@ -1,3 +1,5 @@
+.. _adding-new-scales:
+
 ***********************************************
 Adding new scales and projections to matplotlib
 ***********************************************
@@ -28,6 +30,7 @@ code for scales and projections can be included anywhere: directly
 within a plot script, in third-party code, or in the matplotlib source
 tree itself.
 
+.. _creating-new-scale:
 
 Creating a new scale
 ====================
@@ -63,6 +66,8 @@ A full-fledged and heavily annotated example is in
 in :mod:`matplotlib.scale` that may be used as starting points.
 
 
+.. _creating-new-projection:
+
 Creating a new projection
 =========================
 
diff --git a/doc/devel/coding_guide.rst b/doc/devel/coding_guide.rst
@@ -1,9 +1,16 @@
-***************
+.. _coding-guide:
+
+************
+Coding Guide
+************
+
+.. _version-control:
+
 Version Control
-***************
+===============
 
 svn checkouts
-=============
+-------------
 
 Checking out everything in the trunk (matplotlib and toolkits)::
 
@@ -21,7 +28,7 @@ Branch checkouts, eg the maintenance branch::
    v0_91_maint mpl91 --username=youruser --password=yourpass
 
 Committing changes
-==================
+------------------
 
 When committing changes to matplotlib, there are a few things to bear
 in mind.
@@ -74,12 +81,14 @@ in mind.
 
        > svn commit -F svnmerge-commit-message.txt
 
-***********
+
+.. _style-guide:
+
 Style Guide
-***********
+===========
 
 Importing and name spaces
-=========================
+-------------------------
 
 For `numpy <http://www.numpy.org>`_, use::
 
@@ -115,7 +124,7 @@ function to the new developer.  The former makes it explcit that
 you are importing a module or package.
 
 Naming, spacing, and formatting conventions
-===========================================
+-------------------------------------------
 
 In general, we want to hew as closely as possible to the standard
 coding guidelines for python written by Guido in `PEP 0008
@@ -172,7 +181,7 @@ for older versions of emacs (emacs<22) you need to do:
             (add-hook 'local-write-file-hooks 'delete-trailing-whitespace)))
 
 Keyword argument processing
-===========================
+---------------------------
 
 Matplotlib makes extensive use of ``**kwargs`` for pass through
 customizations from one function to another.  A typical example is in
@@ -255,6 +264,8 @@ forced to use ``**kwargs``.  An example is
       elif len(args) == 1:
          ...etc...
 
+.. _docstrings:
+
 Documentation and Docstrings
 ============================
 
@@ -327,9 +338,11 @@ made some manual hacks in this case which violates the "single entry
 point" requirement above; hopefully we'll find a more elegant solution
 before too long.
 
-********
+
+.. _licenses:
+
 Licenses
-********
+========
 
 Matplotlib only uses BSD compatible code.  If you bring in code from
 another project make sure it has a PSF, BSD, MIT or compatible
diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
@@ -1,3 +1,5 @@
+.. _documenting-matplotlib:
+
 **********************
 Documenting Matplotlib
 **********************
@@ -56,6 +58,8 @@ markup and working with Sphinx in general.
 
 .. _documentation: http://sphinx.pocoo.org/contents.html
 
+.. _referring-to-mpl-docs:
+
 Referring to mpl documents
 ==========================
 
@@ -78,6 +82,8 @@ In the ``users`` subdirectory, if I want to refer to a file in the mpl-data dire
    .. literalinclude:: ../mpl_data/matplotlibrc
 
 
+.. _internal-section-refs:
+
 Internal section references
 ===========================
 
@@ -103,4 +109,39 @@ is better than::
 
 In addition, since underscores are widely used by Sphinx itself, let's prefer hyphens to separate words.
 
+.. _emacs-helpers:
+
+Emacs helpers
+=============
+
+There is an emacs mode `rst.el
+<http://docutils.sourceforge.net/tools/editors/emacs/rst.el>`_ which
+automates many important ReST tasks like building and updateing
+table-of-contents, and promoting or demoting section headings.  Here
+is the basic ``.emacs`` configuration::
+
+    (require 'rst)
+    (setq auto-mode-alist
+          (append '(("\\.txt$" . rst-mode)
+                    ("\\.rst$" . rst-mode)
+                    ("\\.rest$" . rst-mode)) auto-mode-alist))
+
+
+Some helpful functions::
+
+    C-c TAB - rst-toc-insert
+
+      Insert table of contents at point
+    
+    C-c C-u - rst-toc-update
+
+        Update the table of contents at point
+
+    C-c C-l rst-shift-region-left
+
+        Shift region to the left
+
+    C-c C-r rst-shift-region-right
+
+        Shift region to the right
 
diff --git a/doc/devel/index.rst b/doc/devel/index.rst
@@ -7,8 +7,6 @@
 :Release: |version|
 :Date: |today|
 
-Introduction to developer's guide here **TODO**.
-
 .. toctree::
 
    coding_guide.rst
diff --git a/doc/faq/howto_faq.rst b/doc/faq/howto_faq.rst
@@ -1,3 +1,5 @@
+.._ howto-faq:
+
 *****
 HOWTO
 *****
@@ -25,7 +27,7 @@ is controlled by the "markeredgewidth" property::
 The other properties that control the tick marker, and all markers,
 are ``markerfacecolor``, ``markeredgecolor``, ``markeredgewidth``,
 ``markersize``.  For more information on configuring ticks, see
-:ref:`artist-tut-axis` and :ref:`artist-tut-tick`.
+:ref:`axis-container` and :ref:`tick-container`.
 
 .. _howto-webapp:
 
diff --git a/doc/faq/index.rst b/doc/faq/index.rst
@@ -1,4 +1,4 @@
-.. _api-index:
+.. _faq-index:
 
 ####################
   The Matplotlib FAQ
diff --git a/doc/faq/installing_faq.rst b/doc/faq/installing_faq.rst
@@ -1,9 +1,9 @@
+.. _installing-faq:
+
 ==================
  Installation FAQ
 ==================
 
-
-
 How do I report a compilation problem?
 ======================================
 
@@ -22,7 +22,13 @@ install directory.  To cleanly rebuild:
     * delete the ``build`` directory in the source tree 
     * delete ``site-packages/matplotlib`` directory in the Python
       installation.  The location of ``site-packages`` is
-      platform-specific.
+      platform-specific.  You can find out where matplotlib is installed by doing::
+
+          > python -c 'import matplotlib; print matplotlib.__file__'
+
+      and then making sure you remove the matplotlib directory (and
+      any matplotlib*.egg files) you find there.
+
     * you may also want to clear some of the cache data that
       matplotlib stores in your ``.matplotlib`` directory.  You can
       find the location of this directory by doing::
@@ -55,7 +61,7 @@ make image files (PNG, SVG, PDF, PS).
 
 There are a two primary ways to configure your backend.  One is to set
 the ``backend`` parameter in you ``matplotlibrc`` file (see
-link:Configuring)::
+:ref:`customizing-matplotlib`)::
 
     backend : WXAgg   # use wxpython with antigrain (agg) rendering  
 
diff --git a/doc/faq/troubleshooting_faq.rst b/doc/faq/troubleshooting_faq.rst
@@ -1,7 +1,10 @@
+.. _troubleshooting-faq:
+
 ===================
 Troubleshooting FAQ
 ===================
 
+
 .. _reporting-problems:
 
 How do I report a problem?
@@ -16,16 +19,26 @@ If not, please provide the following information in your e-mail to the
 <http://lists.sourceforge.net/mailman/listinfo/matplotlib-users>`_:
 
   * your operating system; on Linux/UNIX post the output of ``uname -a``
-  * matplotlib version  : ``import matplotlib; print matplotlib.__version__``
+
+  * matplotlib version::
+
+        python -c `import matplotlib; print matplotlib.__version__`
+
   * where you obtained matplotlib (e.g. your Linux distribution's
     packages or the matplotlib Sourceforge site)
-  * any customizations to your ``matplotlibrc`` file
+
+  * any customizations to your ``matplotlibrc`` file (see
+    :ref:`customizing-matplotlib`).
+
   * if the problem is reproducible, please try to provide a *minimal*,
     standalone Python script that demonstrates the problem
+
   * you can get very helpful debugging output from matlotlib by
     running your script with a ``verbose-helpful`` or
     ``--verbose-debug`` flags and posting the verbose output the
-    lists.
+    lists::
+
+        > python simple_plot.py --verbose-helpful > output.txt
 
 If you compiled matplotlib yourself, please also provide 
 
diff --git a/doc/users/artists.rst b/doc/users/artists.rst
@@ -1,3 +1,5 @@
+.. _artist-tutorial:
+
 ***************
 Artist tutorial
 ***************
@@ -136,6 +138,8 @@ Try creating the figure below.
 .. image:: figures/fig_axes_labels_simple.png
    :scale: 75
 
+.. _customizing-artists:
+
 Customizing your objects
 ========================
 
@@ -231,6 +235,8 @@ docs at http://matplotlib.sourceforge.net/classdocs.html or PDF documentation
 at http://matplotlib.sourceforge.net/api.pdf for a listing of
 properties for a give object.
 
+.. _object-containers:
+
 Object containers
 =================
 
diff --git a/doc/users/customizing.rst b/doc/users/customizing.rst
@@ -1,3 +1,5 @@
+.. _customizing-matplotlib:
+
 Customizing matplotlib
 ======================
 
@@ -20,6 +22,8 @@ do::
     matplotlib.rc('lines', linewidth=2, color='r')
 
 
+.. _matplotlibrc-sample:
+
 A sample matplotlibrc file
 --------------------------
 
diff --git a/doc/users/event_handling.rst b/doc/users/event_handling.rst
@@ -1,3 +1,5 @@
+.. _event-handling-tutorial:
+
 ***********************************
 Event Handling and Picking Tutorial
 ***********************************
@@ -15,6 +17,7 @@ events, including information like which Axes the event occurred in.
 The events also understand the matplotlib coordinate system, and
 report event locations in both pixel and data coordinates.
 
+.. _event-connections:
 
 Event connections
 =================
@@ -58,6 +61,7 @@ resize_event           ResizeEvent  figure canvas is resized
 scroll_event           MouseEvent   mouse scroll wheel is rolled
 =====================  ===========  ===================================
 
+.. _event-attributes:
 
 Event attributes
 ================
@@ -316,6 +320,8 @@ Extra credit solution::
     plt.show()
 
 
+.. _object-picking:
+
 Object Picking
 ==============
 
diff --git a/doc/users/index.rst b/doc/users/index.rst
@@ -7,6 +7,16 @@
 :Release: |version|
 :Date: |today|
 
+.. toctree::
+
+    pyplot_tutorial.rst
+    mathtext.rst
+    navigation_toolbar.rst
+    customizing.rst
+    artists.rst
+    event_handling.rst
+
+
 matplotlib is a library for making 2D plots of arrays in `Python
 <http://www.python.org>`_.  Although it has its origins in emulating
 the `MATLAB™ <http://www.mathworks.com>`_ graphics commands, it does
@@ -90,12 +100,3 @@ from the Python shell in Tkinter on Windows™. My primary use is to
 embed matplotlib in a Gtk+ EEG application that runs on Windows, Linux
 and Macintosh OS X.
 
-.. toctree::
-
-    pyplot_tutorial.rst
-    mathtext.rst
-    navigation_toolbar.rst
-    customizing.rst
-    artists.rst
-    event_handling.rst
-
diff --git a/doc/users/mathtext.rst b/doc/users/mathtext.rst
@@ -1,6 +1,9 @@
+.. _mathtext-tutorial:
+
 Writing mathematical expressions
 ================================
 
+
 You can use TeX markup in any matplotlib text string; see the
 :mod:`matplotlib.mathtext` module documentation for details.  Note
 that you do not need to have TeX installed, since matplotlib ships its
@@ -35,6 +38,7 @@ produces ":math:`\alpha > \beta`".
 
 .. TODO: Include a complete list here
 
+
 Subscripts and superscripts
 ---------------------------
 
diff --git a/doc/users/navigation_toolbar.rst b/doc/users/navigation_toolbar.rst
diff --git a/doc/users/pyplot_tutorial.rst b/doc/users/pyplot_tutorial.rst

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-.. _api-index:`
	`1`	`+.. _faq-index:`
`2`	`2`
`3`	`3`	`####################`
`4`	`4`	`The Matplotlib FAQ`