Revision: 5416
http://matplotlib.svn.sourceforge.net/matplotlib/?rev=5416&view=rev
Author: dsdale
Date: 2008-06-07 14:41:51 -0700 (Sat, 07 Jun 2008)
Log Message:
-----------
updated documentation guide
Modified Paths:
--------------
trunk/matplotlib/doc/devel/documenting_mpl.rst
Added Paths:
-----------
trunk/matplotlib/doc/static_figs/
trunk/matplotlib/doc/static_figs/README
Modified: trunk/matplotlib/doc/devel/documenting_mpl.rst
===================================================================
--- trunk/matplotlib/doc/devel/documenting_mpl.rst 2008-06-07 21:02:24 UTC
(rev 5415)
+++ trunk/matplotlib/doc/devel/documenting_mpl.rst 2008-06-07 21:41:51 UTC
(rev 5416)
@@ -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 @@
.. _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 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 output produced by Sphinx can be configured by editing the `conf.py`
+file located in the `doc\`.
-Sphinx does not support tables with column- or row-spanning cells for
-latex output. Such tables can not be used when documenting matplotlib.
+Organization of Matplotlib's Documentation
+==========================================
-Mathematical expressions can be rendered as png images in html, and in
-the usual way by latex. For example:
+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.
-``math:`sin(x_n^2)`` yields: :math:`sin(x_n^2)`, and::
+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 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.
+
+* 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::
\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}}
+ \int_{-\infty}^{\infty}\frac{e^{i\phi}}{1+x^2\frac{e^{i\phi}}{1+x^2}}
-The output produced by Sphinx can be configured by editing the conf.py
-files located in the documentation source directories.
+* Interactive IPython sessions can be illustrated in the documentation using
+ the following directive::
-The Sphinx website contains plenty of documentation_ concerning ReST
-markup and working with Sphinx in general.
+ .. sourcecode:: ipython
+ In [69]: lines = plot([1,2,3])
+
+which would yield::
+
+.. sourcecode:: ipython
+
+ 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 @@
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 @@
.. _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:
Added: trunk/matplotlib/doc/static_figs/README
===================================================================
--- trunk/matplotlib/doc/static_figs/README (rev 0)
+++ trunk/matplotlib/doc/static_figs/README 2008-06-07 21:41:51 UTC (rev
5416)
@@ -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.
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
