updated documentation guide

ddale · ddale · commit f81164abf984 · 2008-06-07T21:41:51.000Z
svn path=/trunk/matplotlib/; revision=5416
diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
@@ -4,6 +4,9 @@
 Documenting Matplotlib
 **********************
 
+Getting Started
+===============
+
 The documentation for matplotlib is generated from ReStructured Text
 using the Sphinx_ documentation generation tool. Sphinx-0.4 or later
 is required. Currently this means we need to install from the svn
@@ -15,56 +18,100 @@ repository by doing::
 
 .. _Sphinx: http://sphinx.pocoo.org/
 
-The documentation sources are found in the doc/ directory in the trunk.
-To build the users guid in html format, cd into doc/users_guide and do::
+The documentation sources are found in the `doc/` directory in the trunk.
+To build the users guide in html format, cd into `doc/users_guide` and do::
 
   python make.py html
 
+or::
+
+  ./make.py html
+
 you can also pass a ``latex`` flag to make.py to build a pdf, or pass no
-arguments to build everything. The same procedure can be followed for
-the sources in doc/api_reference.
+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
+==========================================
+
+The actual ReStructured Text files are kept in `doc/users`, `doc/devel`,
+`doc/api` and `doc/faq`. The main entry point is `doc/index.rst`, which pulls
+in the `index.rst` file for the users guide, developers guide, api reference,
+and faqs. The documentation suite is built as a single document in order to
+make the most effective use of cross referencing, we want to make navigating
+the Matplotlib documentation as easy as possible.
+
+Additional files can be added to the various guides by including their base
+file name (the .rst extension is not necessary) in the table of contents.
+It is also possible to include other documents through the use of an include
+statement, such as::
+
+  .. include:: ../../TODO
+
+Formatting
+==========
 
-The actual ReStructured Text files are kept in doc/users_guide/source
-and doc/api_reference/source. The main entry point is index.rst.
-Additional files can be added by including their base file name
-(dropping the .rst extension) in the table of contents. It is also
-possible to include other documents through the use of an include
-statement. For example, in the Developers Guide, index.rst lists
-coding_guide, which automatically inserts coding_guide.rst.
+The Sphinx website contains plenty of documentation_ concerning ReST markup and
+working with Sphinx in general. Here are a few additional things to keep in mind:
 
-Sphinx does not support tables with column- or row-spanning cells for
-latex output. Such tables can not be used when documenting matplotlib.
+* Sphinx does not support tables with column- or row-spanning cells for
+  latex output. Such tables can not be used when documenting matplotlib.
 
-Mathematical expressions can be rendered as png images in html, and in
-the usual way by latex. For example:
+* Mathematical expressions can be rendered as png images in html, and in
+  the usual way by latex. For example:
 
-``math:`sin(x_n^2)`` yields: :math:`sin(x_n^2)`, and::
+  ``math:`sin(x_n^2)`` yields: :math:`sin(x_n^2)`, and::
 
   .. math::
 
      \int_{-\infty}^{\infty}\frac{e^{i\phi}}{1+x^2\frac{e^{i\phi}}{1+x^2}}``
 
-yields:
+  yields:
 
-.. math::
+  .. math::
+
+    \int_{-\infty}^{\infty}\frac{e^{i\phi}}{1+x^2\frac{e^{i\phi}}{1+x^2}}
+
+* Interactive IPython sessions can be illustrated in the documentation using
+  the following directive::
+
+    .. sourcecode:: ipython
+
+      In [69]: lines = plot([1,2,3])
 
-   \int_{-\infty}^{\infty}\frac{e^{i\phi}}{1+x^2\frac{e^{i\phi}}{1+x^2}}
+which would yield::
 
-The output produced by Sphinx can be configured by editing the conf.py
-files located in the documentation source directories.
+.. sourcecode:: ipython
 
-The Sphinx website contains plenty of documentation_ concerning ReST
-markup and working with Sphinx in general.
+    In [69]: lines = plot([1,2,3])
 
 .. _documentation: http://sphinx.pocoo.org/contents.html
 
+
+Figures
+=======
+
+Each guide will have its own figures directory for scripts to generate images
+to be included in the dcoumentation. It is not necessary to explicitly save
+the figure in the script, a figure will be saved with the same name as the
+filename when the documentation is generated.
+
+Any figures that rely on optional system configurations should be generated
+with a script residing in doc/static_figs. The resulting figures will be saved
+to doc/_static, and will be named based on the name of the script, so we can
+avoid unintentionally overwriting any existing figures. Please add a line to
+the README in doc/static-figs for any additional requirements necessary to
+generate a new figure.
+
 .. _referring-to-mpl-docs:
 
 Referring to mpl documents
 ==========================
 
 In the documentation, you may want to include to a document in the
-matplotlib src, eg a license file, an image file from ``mpl-data``, or an
+matplotlib src, eg a license file, an image file from `mpl-data`, or an
 example.  When you include these files, include them using a symbolic
 link from the documentation parent directory.  This way, if we
 relocate the mpl documentation directory, all of the internal pointers
@@ -77,7 +124,9 @@ the mpl ``examples`` and ``mpl-data``::
     mpl_examples -> ../examples
 
 
-In the ``users`` subdirectory, if I want to refer to a file in the mpl-data directory, I use the symlink direcotry.  For example, from ``customizing.rst``::
+In the `users` subdirectory, if I want to refer to a file in the mpl-data
+directory, I use the symlink directory.  For example, from
+``customizing.rst``::
 
    .. literalinclude:: ../mpl_data/matplotlibrc
 
@@ -107,7 +156,8 @@ is better than::
 
     .. _faq-backend
 
-In addition, since underscores are widely used by Sphinx itself, let's prefer hyphens to separate words.
+In addition, since underscores are widely used by Sphinx itself, let's prefer
+hyphens to separate words.
 
 .. _emacs-helpers:
 
diff --git a/doc/static_figs/README b/doc/static_figs/README
@@ -0,0 +1,4 @@
+Scripts that require optional system configurations to generate scripts should go here. The 
+figures will be generated in doc/_static, and will be named based on the name of the script, 
+so we can avoid unintentionally overwriting any existing figures. Please add a line to this 
+file for any additional requirements necessary to generate a new figure.
