Menu
▾
▴
SF.net SVN: matplotlib: [5467] trunk/matplotlib/doc
|
From: <jd...@us...> - 2008-06-11 01:26:34
|
Revision: 5467
http://matplotlib.svn.sourceforge.net/matplotlib/?rev=5467&view=rev
Author: jdh2358
Date: 2008-06-10 18:26:29 -0700 (Tue, 10 Jun 2008)
Log Message:
-----------
added usetex review
Modified Paths:
--------------
trunk/matplotlib/doc/devel/coding_guide.rst
trunk/matplotlib/doc/devel/documenting_mpl.rst
trunk/matplotlib/doc/devel/outline.rst
trunk/matplotlib/doc/users/usetex.rst
Modified: trunk/matplotlib/doc/devel/coding_guide.rst
===================================================================
--- trunk/matplotlib/doc/devel/coding_guide.rst 2008-06-11 00:29:14 UTC (rev 5466)
+++ trunk/matplotlib/doc/devel/coding_guide.rst 2008-06-11 01:26:29 UTC (rev 5467)
@@ -1,12 +1,12 @@
.. _coding-guide:
************
-Coding Guide
+Coding guide
************
.. _version-control:
-Version Control
+Version control
===============
svn checkouts
@@ -35,18 +35,25 @@
* if your changes are non-trivial, please make an entry in the
:file:`CHANGELOG`
-* if you change the API, please document it in :file:`API_CHANGES`, and
- consider posting to mpl-devel
-* Are your changes python2.4 compatible? We are still trying to
- support 2.4, so avoid features new to 2.5
+
+* if you change the API, please document it in :file:`API_CHANGES`,
+ and consider posting to `mpl-devel
+ <http://lists.sourceforge.net/mailman/listinfo/matplotlib-devel>`_
+
+* Are your changes python2.4 compatible? We still support 2.4, so
+ avoid features new to 2.5
+
* Can you pass :file:`examples/tests/backend_driver.py`? This is our
poor man's unit test.
+
* If you have altered extension code, do you pass
:file:`unit/memleak_hawaii.py`?
+
* if you have added new files or directories, or reorganized existing
ones, are the new files included in the match patterns in
:file:`MANIFEST.in`. This file determines what goes into the source
distribution of the mpl build.
+
* Keep the maintenance branch and trunk in sync where it makes sense.
If there is a bug on both that needs fixing, use `svnmerge.py
<http://www.orcaware.com/svn/wiki/Svnmerge.py>`_ to keep them in
@@ -58,6 +65,7 @@
svnmerge/svnmerge.py
* get a svn copy of the maintenance branch and the trunk (see above)
+
* Michael advises making the change on the branch and committing
it. Make sure you svn upped on the trunk and have no local
modifications, and then from the svn trunk do::
@@ -87,7 +95,7 @@
.. _style-guide:
-Style Guide
+Style guide
===========
Importing and name spaces
@@ -278,7 +286,7 @@
.. _docstrings:
-Documentation and Docstrings
+Documentation and docstrings
============================
matplotlib uses artist introspection of docstrings to support
Modified: trunk/matplotlib/doc/devel/documenting_mpl.rst
===================================================================
--- trunk/matplotlib/doc/devel/documenting_mpl.rst 2008-06-11 00:29:14 UTC (rev 5466)
+++ trunk/matplotlib/doc/devel/documenting_mpl.rst 2008-06-11 01:26:29 UTC (rev 5467)
@@ -1,10 +1,10 @@
.. _documenting-matplotlib:
**********************
-Documenting Matplotlib
+Documenting matplotlib
**********************
-Getting Started
+Getting started
===============
The documentation for matplotlib is generated from ReStructured Text
@@ -33,7 +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
+Organization of matplotlib's documentation
==========================================
The actual ReStructured Text files are kept in `doc/users`, `doc/devel`,
@@ -96,8 +96,14 @@
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.
+filename when the documentation is generated. For example, use::
+ .. literalinclude:: figures/pyplot_simple.py
+
+ .. image:: figures/pyplot_simple.png
+ :scale: 75
+
+
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
@@ -105,6 +111,8 @@
the README in doc/static-figs for any additional requirements necessary to
generate a new figure.
+
+
.. _referring-to-mpl-docs:
Referring to mpl documents
@@ -131,6 +139,8 @@
.. literalinclude:: ../mpl_data/matplotlibrc
+
+
.. _internal-section-refs:
Internal section references
@@ -161,6 +171,13 @@
.. _emacs-helpers:
+Section names, etc
+==================
+
+For everything but top level chapters, please use ``Upper lower`` for
+section titles, eg ``Possible hangups`` rather than ``Possible
+Hangups``
+
Emacs helpers
=============
@@ -182,7 +199,7 @@
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
Modified: trunk/matplotlib/doc/devel/outline.rst
===================================================================
--- trunk/matplotlib/doc/devel/outline.rst 2008-06-11 00:29:14 UTC (rev 5466)
+++ trunk/matplotlib/doc/devel/outline.rst 2008-06-11 01:26:29 UTC (rev 5467)
@@ -28,7 +28,7 @@
animation John has author ?
collections ? no author ?
text - mathtext Michael in review John
-text - usetex Darren submitted ?
+text - usetex Darren in review John
text - annotations John submitted ?
fonts et al Michael ? no author Darren
pyplot tut John submitted Eric
@@ -177,4 +177,40 @@
sub-packages with the gamut of licenses, GPL to MIT?
+usetex user's guide-- reviewed by JDH
+-------------------------------------
+Review of :ref:`usetex-tutorial`:
+
+#. In the section on the ps distiller, you might mention that it is
+ the rasterization which some users find objectionable, and the
+ distiller pram (eg 6000) is a dpi setting for the rasterizer. Not
+ everyone will immediately grasp the controversy surrounding dumping
+ high res bitmaps into a ps file.
+
+#. ``= Possible Hangups =`` - this is moin, not rest. I have fixed
+ this already, just wanted to point it out. Also, for everything
+ but top level chapters, I refer ``Upper lower`` for section
+ titles, eg ``Possible hangups``.
+
+#. in the troubleshooting section, could you add a FAQ showing how to
+ find their .matplotlib dir (matplotlib.get_data_path) and link to
+ it. Also link to the PATH var and properly format
+ ``text.latex.preample``. For the dirs, do we want `tex.cache` or
+ ``tex.cache``? I've been using the latter. We could use rest
+ specific markup for files and dirs, but I've been resisting goin
+ whle hog onthe markup... But we may eventually decide that is the
+ better choice.
+
+#. try and use internal reference links for every section and be
+ generous with the sections. Eg, I added a section headers and
+ internal linka for the postscript and unicode sections (we will
+ want to be able to refer people to these easily from FAQs and mail
+ list posts, etc)::
+
+ .. _usetex-postscript:
+
+ Postscript options
+ ==================
+
+Looks good!
Modified: trunk/matplotlib/doc/users/usetex.rst
===================================================================
--- trunk/matplotlib/doc/users/usetex.rst 2008-06-11 00:29:14 UTC (rev 5466)
+++ trunk/matplotlib/doc/users/usetex.rst 2008-06-11 01:26:29 UTC (rev 5467)
@@ -52,7 +52,7 @@
Here is the standard example, `tex_demo.py`:
- .. literalinclude:: ../mpl_examples/pylab_examples/tex_demo.py
+.. literalinclude:: ../mpl_examples/pylab_examples/tex_demo.py
.. image:: ../_static/tex_demo.png
@@ -60,13 +60,22 @@
command ``\displaystyle``, as in `tex_demo.py`, will produce the same
results.
+.. _usetex-unicode:
+
+usetex with unicode
+===================
It is also possible to use unicode strings with the LaTeX text manager, here is
an example taken from `tex_unicode_demo.py`:
- .. literalinclude:: ../mpl_examples/pylab_examples/tex_unicode_demo.py
+.. literalinclude:: ../mpl_examples/pylab_examples/tex_unicode_demo.py
.. image:: ../_static/tex_unicode_demo.png
+.. _usetex-postscript:
+
+Postscript options
+==================
+
In order to produce encapsulated postscript files that can be embedded in a new
LaTeX document, the default behavior of matplotlib is to distill the output,
which removes some postscript operators used by LaTeX that are illegal in an
@@ -77,51 +86,60 @@
alternative produces postscript with text that can be edited in Adobe
Illustrator, and searched text in pdf documents.
+.. _usetex-hangups:
-= Possible Hangups =
+Possible hangups
+================
- * On Windows, the PATH environment variable may need to be modified to find
- the latex, dvipng and ghostscript executables. This is done by going to the
- control panel, selecting the "system" icon, selecting the "advanced" tab,
- and clicking the "environment variables" button (and people think Linux is
- complicated. Sheesh.) Select the PATH variable, and add the appropriate
- directories.
+* On Windows, the PATH environment variable may need to be modified to
+ find the latex, dvipng and ghostscript executables. This is done by
+ going to the control panel, selecting the "system" icon, selecting
+ the "advanced" tab, and clicking the "environment variables" button
+ (and people think Linux is complicated. Sheesh.) Select the PATH
+ variable, and add the appropriate directories.
- * Using MiKTeX with Computer Modern fonts, if you get odd -Agg and PNG
- results, go to MiKTeX/Options and update your format files
+* Using MiKTeX with Computer Modern fonts, if you get odd -Agg and PNG
+ results, go to MiKTeX/Options and update your format files
- * The fonts look terrible on screen. You are probably running Mac OS, and
- there is some funny business with dvipng on the mac. Set text.dvipnghack :
- True in your matplotlibrc file.
+* The fonts look terrible on screen. You are probably running Mac OS,
+ and there is some funny business with dvipng on the mac. Set
+ text.dvipnghack : True in your matplotlibrc file.
- * On Ubuntu and Gentoo, the base texlive install does not ship with the
- type1cm package. You may need to install some of the extra packages to get
- all the goodies that come bundled with other latex distributions.
+* On Ubuntu and Gentoo, the base texlive install does not ship with
+ the type1cm package. You may need to install some of the extra
+ packages to get all the goodies that come bundled with other latex
+ distributions.
- * Some progress has been made so Matplotlib uses the dvi files directly for
- text layout. This allows latex to be used for text layout with the pdf and
- svg backends, as well as the \*Agg and PS backends. In the future, a latex
- installation may be the only external dependency.
+* Some progress has been made so Matplotlib uses the dvi files
+ directly for text layout. This allows latex to be used for text
+ layout with the pdf and svg backends, as well as the \*Agg and PS
+ backends. In the future, a latex installation may be the only
+ external dependency.
-= In the event that things dont work =
- * Try deleting `tex.cache` from your `~/.matplotlib` directory
+.. _usetex-troubleshooting:
- * Make sure LaTeX, dvipng and ghostscript are each working and on your PATH.
+Trouble shooting
+================
- * Make sure what you are trying to do is possible in a LaTeX document, that
- your LaTeX syntax is valid and that you are using raw strings if necessary
- to avoid unintended escape sequences.
+* Try deleting `tex.cache` from your `~/.matplotlib` directory
- * Most problems reported on the mailing list have been cleared up by
- upgrading Ghostscript_. If possible, please try upgrading to the latest
- release before reporting problems to the list.
+* Make sure LaTeX, dvipng and ghostscript are each working and on your PATH.
- * The text.latex.preample rc setting is not officially supported. This option
- provides lots of flexibility, and lots of ways to cause problems. Please
- disable this option before reporting problems to the mailing list.
+* Make sure what you are trying to do is possible in a LaTeX document,
+ that your LaTeX syntax is valid and that you are using raw strings
+ if necessary to avoid unintended escape sequences.
- * If you still need help, please see :ref:`reporting-problems`
+* Most problems reported on the mailing list have been cleared up by
+ upgrading Ghostscript_. If possible, please try upgrading to the
+ latest release before reporting problems to the list.
+* The text.latex.preample rc setting is not officially supported. This
+ option provides lots of flexibility, and lots of ways to cause
+ problems. Please disable this option before reporting problems to
+ the mailing list.
+
+* If you still need help, please see :ref:`reporting-problems`
+
.. _LaTeX: http://www.tug.org
.. _dvipng: http://sourceforge.net/projects/dvipng
.. _Ghostscript: http://www.cs.wisc.edu/~ghost/
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
