Revision: 7457
http://matplotlib.svn.sourceforge.net/matplotlib/?rev=7457&view=rev
Author: jdh2358
Date: 2009-08-11 11:22:28 +0000 (Tue, 11 Aug 2009)
Log Message:
-----------
added pyplots and extensions
Modified Paths:
--------------
trunk/py4science/examples/sphinx_qs/cheatsheet.rst
trunk/py4science/examples/sphinx_qs/custom_look.rst
trunk/py4science/examples/sphinx_qs/getting_started.rst
trunk/py4science/examples/sphinx_qs/index.rst
Added Paths:
-----------
trunk/py4science/examples/sphinx_qs/emacs_help.rst
trunk/py4science/examples/sphinx_qs/pyplots/
trunk/py4science/examples/sphinx_qs/pyplots/ellipses.py
trunk/py4science/examples/sphinx_qs/sphinx_extensions.rst
Modified: trunk/py4science/examples/sphinx_qs/cheatsheet.rst
===================================================================
--- trunk/py4science/examples/sphinx_qs/cheatsheet.rst 2009-08-11 10:59:31 UTC
(rev 7456)
+++ trunk/py4science/examples/sphinx_qs/cheatsheet.rst 2009-08-11 11:22:28 UTC
(rev 7457)
@@ -1,38 +1,162 @@
-.. _sphinx_helpers:
-
-
-******************
-Sphinx Cheat Sheet
-******************
-
-Cheat sheet on how to make this site and install these extensions and
-other goodies. You can see a literal version of this file below in
-:ref:`sphinx-literal`.
-
-.. _installing-docdir:
-Installing your doc directory
-=============================
-
-You may already have sphinx `sphinx <http://sphinx.pocoo.org/>`_
-installed -- you can check by doing::
-
- python -c 'import sphinx'
-
-If that fails grab the latest version of and install it with::
-
- > sudo easy_install sphinx
-
-Now you are ready to build a template for your docs, using
-sphinx-quickstart::
-
- > sphinx-quickstart
-
-accepting most of the defaults. I choose "py4sci" as the name of my project
-
-We can test the installation by changing into the project directory,
-and typing `make html`::
-
- cd py4sci
- make html
-
-
+.. _cheat-sheet:
+
+******************
+Sphinx cheat sheet
+******************
+
+Here is a quick and dirty cheat sheet for some common stuff you want
+to do in sphinx and ReST. You can see the literal source for this
+file at :ref:`cheatsheet
+-literal`.
+
+
+.. _formatting-text:
+
+Formatting text
+===============
+
+You use inline markup to make text *italics*, **bold**, or ``monotype``.
+
+You can represent code blocks fairly easily::
+
+ import numpy as np
+ x = np.random.rand(12)
+
+Or literally include code:
+
+.. literalinclude:: ../pyplots/ellipses.py
+
+
+
+.. _making-a-list:
+
+Making a list
+=============
+
+It is easy to make lists in rest
+
+Bullet points
+-------------
+
+This is a subsection making bullet points
+
+* point A
+
+* point B
+
+* point C
+
+
+Enumerated points
+------------------
+
+This is a subsection making numbered points
+
+#. point A
+
+#. point B
+
+#. point C
+
+
+.. _making-a-table:
+
+Making a table
+==============
+
+This shows you how to make a table -- if you only want to make a list see
:ref:`making-a-list`.
+
+================== ============
+Name Age
+================== ============
+John D Hunter 40
+Cast of Thousands 41
+And Still More 42
+================== ============
+
+.. _making-links:
+
+Making links
+============
+
+It is easy to make a link to `yahoo <http://yahoo.com>`_ or to some
+section inside this document (see :ref:`making-a-table`) or another
+document (see :ref:`final-results`).
+
+You can also reference classes, modules, functions, etc that are
+documented using the sphinx `autodoc
+<http://sphinx.pocoo.org/ext/autodoc.html>`_ facilites. For example,
+see the module :mod:`matplotlib.backend_bases` documentation, or the
+class :class:`~matplotlib.backend_bases.LocationEvent`, or the method
+:meth:`~matplotlib.backend_bases.FigureCanvasBase.mpl_connect`.
+
+
+
+.. _making-a-list:
+
+Making a list
+=============
+
+It is easy to make lists in rest
+
+Bullet points
+-------------
+
+This is a subsection making bullet points
+
+* point A
+
+* point B
+
+* point C
+
+
+Enumerated points
+------------------
+
+This is a subsection making numbered points
+
+#. point A
+
+#. point B
+
+#. point C
+
+
+.. _making-a-table:
+
+Making a table
+==============
+
+This shows you how to make a table -- if you only want to make a list see
:ref:`making-a-list`.
+
+================== ============
+Name Age
+================== ============
+John D Hunter 40
+Cast of Thousands 41
+And Still More 42
+================== ============
+
+.. _making-links:
+
+Making links
+============
+
+It is easy to make a link to `yahoo <http://yahoo.com>`_ or to some
+section inside this document (see :ref:`making-a-table`) or another
+document (see :ref:`final-results`).
+
+You can also reference classes, modules, functions, etc that are
+documented using the sphinx `autodoc
+<http://sphinx.pocoo.org/ext/autodoc.html>`_ facilites. For example,
+see the module :mod:`matplotlib.backend_bases` documentation, or the
+class :class:`~matplotlib.backend_bases.LocationEvent`, or the method
+:meth:`~matplotlib.backend_bases.FigureCanvasBase.mpl_connect`.
+
+.. _cheatsheet-literal:
+
+This file
+=========
+
+.. literalinclude:: cheatsheet.rst
Modified: trunk/py4science/examples/sphinx_qs/custom_look.rst
===================================================================
--- trunk/py4science/examples/sphinx_qs/custom_look.rst 2009-08-11 10:59:31 UTC
(rev 7456)
+++ trunk/py4science/examples/sphinx_qs/custom_look.rst 2009-08-11 11:22:28 UTC
(rev 7457)
@@ -1,9 +1,9 @@
.. _custom_look:
-*********************
-Customizing the site
-*********************
+******************************************
+Customizing the look and feel of the site
+******************************************
The `sphinx <http://sphinx.pocoo.org/>`_ site itself looks better than
the sites created with the default css, so here we'll invoke Tufte's
Added: trunk/py4science/examples/sphinx_qs/emacs_help.rst
===================================================================
--- trunk/py4science/examples/sphinx_qs/emacs_help.rst
(rev 0)
+++ trunk/py4science/examples/sphinx_qs/emacs_help.rst 2009-08-11 11:22:28 UTC
(rev 7457)
@@ -0,0 +1,40 @@
+.. _working-with-emacs:
+
+*******************
+Emacs ReST support
+*******************
+
+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
+
Modified: trunk/py4science/examples/sphinx_qs/getting_started.rst
===================================================================
--- trunk/py4science/examples/sphinx_qs/getting_started.rst 2009-08-11
10:59:31 UTC (rev 7456)
+++ trunk/py4science/examples/sphinx_qs/getting_started.rst 2009-08-11
11:22:28 UTC (rev 7457)
@@ -6,8 +6,7 @@
***************
Cheat sheet on how to make this site and install these extensions and
-other goodies. You can see a literal version of this file below in
-:ref:`sphinx-literal`.
+other goodies.
.. _installing-docdir:
Installing your doc directory
@@ -106,4 +105,3 @@
the `sphinx <http://sphinx.pocoo.org/>`_ site itself -- see
:ref:`custom_look`.
-
Modified: trunk/py4science/examples/sphinx_qs/index.rst
===================================================================
--- trunk/py4science/examples/sphinx_qs/index.rst 2009-08-11 10:59:31 UTC
(rev 7456)
+++ trunk/py4science/examples/sphinx_qs/index.rst 2009-08-11 11:22:28 UTC
(rev 7457)
@@ -13,6 +13,7 @@
getting_started.rst
custom_look.rst
+ sphinx_extensions.rst
Indices and tables
==================
Added: trunk/py4science/examples/sphinx_qs/pyplots/ellipses.py
===================================================================
--- trunk/py4science/examples/sphinx_qs/pyplots/ellipses.py
(rev 0)
+++ trunk/py4science/examples/sphinx_qs/pyplots/ellipses.py 2009-08-11
11:22:28 UTC (rev 7457)
@@ -0,0 +1,19 @@
+from pylab import *
+from matplotlib.patches import Ellipse
+
+delta = 45.0 # degrees
+
+angles = arange(0, 360+delta, delta)
+ells = [Ellipse((1, 1), 4, 2, a) for a in angles]
+
+a = subplot(111, aspect='equal')
+
+for e in ells:
+ e.set_clip_box(a.bbox)
+ e.set_alpha(0.1)
+ a.add_artist(e)
+
+xlim(-2, 4)
+ylim(-1, 3)
+
+show()
Added: trunk/py4science/examples/sphinx_qs/sphinx_extensions.rst
===================================================================
--- trunk/py4science/examples/sphinx_qs/sphinx_extensions.rst
(rev 0)
+++ trunk/py4science/examples/sphinx_qs/sphinx_extensions.rst 2009-08-11
11:22:28 UTC (rev 7457)
@@ -0,0 +1,154 @@
+.. _extensions:
+
+
+****************************************************
+Sphinx extensions for embedded plots, math and more
+****************************************************
+
+Sphinx is written in python, and supports the ability to write custom
+extensions. We've written a few for the matplotlib documentation,
+some of which are part of matplotlib itself in the
+matplotlib.sphinxext module, some of which are included only in the
+sphinx doc directory, and there are other extensions written by other
+groups, eg numpy and ipython. We're collecting these in this tutorial
+and showing you how to install and use them for your own project.
+First let's grab the python extension files from the :file:`sphinxext`
+directory from svn (see :ref:`getting-the-data`, and install them in
+our :file:`py4sci` project :file:`sphinxext` directory::
+
+ home:~/tmp/py4sci> mkdir sphinxext
+ home:~/tmp/py4sci> cp ../sphinx_qs/sphinxext/*.py sphinxext/
+ home:~/tmp/py4sci> ls sphinxext/
+ apigen.py inheritance_diagram.py
+ docscrape.py ipython_console_highlighting.py
+ docscrape_sphinx.py numpydoc.py
+
+In addition to the builtin matplotlib extensions for embedding pyplot
+plots and rendering math with matplotlib's native math engine, we also
+have extensions for syntax highlighting ipython sessions, making
+inhertiance diagrams, and more.
+
+We need to inform sphinx of our new extensions in the :file:`conf.py`
+file by adding the following. First we tell it where to find the extensions::
+
+ # If your extensions are in another directory, add it here. If the
+ # directory is relative to the documentation root, use
+ # os.path.abspath to make it absolute, like shown here.
+ sys.path.append(os.path.abspath('sphinxext'))
+
+And then we tell it what extensions to load::
+
+ # Add any Sphinx extension module names here, as strings. They can
+ # be extensions coming with Sphinx (named 'sphinx.ext.*') or your
+ # custom ones.
+ extensions = ['matplotlib.sphinxext.mathmpl',
+ 'matplotlib.sphinxext.only_directives',
+ 'matplotlib.sphinxext.plot_directive',
+ 'sphinx.ext.autodoc',
+ 'sphinx.ext.doctest',
+ 'ipython_console_highlighting',
+ 'inheritance_diagram',
+ 'numpydoc']
+
+
+Now let's look at some of these in action. You can see the literal
+source for this file at :ref:`sphinx-extensions-literal`.
+
+
+.. _ipython-highlighting:
+
+ipython sessions
+================
+
+Michael Droettboom contributed a sphinx extension which does pygments
+syntax highlighting on ipython sessions
+
+.. sourcecode:: ipython
+
+ In [69]: lines = plot([1,2,3])
+
+ In [70]: setp(lines)
+ alpha: float
+ animated: [True | False]
+ antialiased or aa: [True | False]
+ ...snip
+
+This support is included in this template, but will also be included
+in a future version of Pygments by default.
+
+.. _using-math:
+
+Using math
+==========
+
+In sphinx you can include inline math :math:`x\leftarrow y\ x\forall
+y\ x-y` or display math
+
+.. math::
+
+ W^{3\beta}_{\delta_1 \rho_1 \sigma_2} = U^{3\beta}_{\delta_1 \rho_1} +
\frac{1}{8 \pi 2} \int^{\alpha_2}_{\alpha_2} d \alpha^\prime_2 \left[\frac{
U^{2\beta}_{\delta_1 \rho_1} - \alpha^\prime_2U^{1\beta}_{\rho_1 \sigma_2}
}{U^{0\beta}_{\rho_1 \sigma_2}}\right]
+
+This documentation framework includes a Sphinx extension,
+:file:`sphinxext/mathmpl.py`, that uses matplotlib to render math
+equations when generating HTML, and LaTeX itself when generating a
+PDF. This can be useful on systems that have matplotlib, but not
+LaTeX, installed. To use it, add ``mathmpl`` to the list of
+extensions in :file:`conf.py`.
+
+Current SVN versions of Sphinx now include built-in support for math.
+There are two flavors:
+
+ - pngmath: uses dvipng to render the equation
+
+ - jsmath: renders the math in the browser using Javascript
+
+To use these extensions instead, add ``sphinx.ext.pngmath`` or
+``sphinx.ext.jsmath`` to the list of extensions in :file:`conf.py`.
+
+All three of these options for math are designed to behave in the same
+way.
+
+.. _emacs-helpers:
+
+Inserting matplotlib plots
+==========================
+
+Inserting automatically-generated plots is easy. Simply put the
+script to generate the plot in the :file:`pyplots` directory, and
+refer to it using the ``plot`` directive. To include the source code
+for the plot in the document, pass the ``include-source`` parameter::
+
+ .. plot:: ../pyplots/ellipses.py
+ :include-source:
+
+In the HTML version of the document, the plot includes links to the
+original source code, a high-resolution PNG and a PDF. In the PDF
+version of the document, the plot is included as a scalable PDF.
+
+.. plot:: pyplots/elegant.py
+ :include-source:
+
+Inheritance diagrams
+====================
+
+Inheritance diagrams can be inserted directly into the document by
+providing a list of class or module names to the
+``inheritance-diagram`` directive.
+
+For example::
+
+ .. inheritance-diagram:: codecs
+
+produces:
+
+.. inheritance-diagram:: codecs
+
+
+.. _sphinx-extensions-literal:
+
+This file
+=========
+
+.. literalinclude:: sphinx_extensions.rst
+
+
This was sent by the SourceForge.net collaborative development platform, the
world's largest Open Source development site.
------------------------------------------------------------------------------
Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day
trial. Simplify your report design, integration and deployment - and focus on
what you do best, core application coding. Discover what's new with
Crystal Reports now. http://p.sf.net/sfu/bobj-july
_______________________________________________
Matplotlib-checkins mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/matplotlib-checkins
