Menu
▾
▴
SF.net SVN: matplotlib:[7466] trunk/py4science/examples/sphinx_qs
|
From: <jd...@us...> - 2009-08-11 12:07:24
|
Revision: 7466
http://matplotlib.svn.sourceforge.net/matplotlib/?rev=7466&view=rev
Author: jdh2358
Date: 2009-08-11 12:07:15 +0000 (Tue, 11 Aug 2009)
Log Message:
-----------
moving to trunk
Removed Paths:
-------------
trunk/py4science/examples/sphinx_qs/custom_look.rst
trunk/py4science/examples/sphinx_qs/emacs_help.rst
trunk/py4science/examples/sphinx_qs/extensions.rst
trunk/py4science/examples/sphinx_qs/getting_started.rst
trunk/py4science/examples/sphinx_qs/index.rst
trunk/py4science/examples/sphinx_qs/pyplots/
trunk/py4science/examples/sphinx_qs/sphinxext/
Deleted: trunk/py4science/examples/sphinx_qs/custom_look.rst
===================================================================
--- trunk/py4science/examples/sphinx_qs/custom_look.rst 2009-08-11 12:06:06 UTC (rev 7465)
+++ trunk/py4science/examples/sphinx_qs/custom_look.rst 2009-08-11 12:07:15 UTC (rev 7466)
@@ -1,62 +0,0 @@
-.. _custom_look:
-
-
-******************************************
-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
-phrase "Intelligence imitates but genious steals and grab their css
-and part of their layout. As before, you can either get the required
-files :file:`_static/default.css`, :file:`_templates:layout.html` and
-:file:`_static\logo.png` from the website or svn (see
-:ref:`fetching-the-data`). Since I did a svn checkout before, I will
-just copy the stuff I need from there::
-
- home:~/tmp/sampledoc> cp ../sampledoc_tut/_static/default.css _static/
- home:~/tmp/sampledoc> cp ../sampledoc_tut/_templates/layout.html _templates/
- home:~/tmp/sampledoc> cp ../sampledoc_tut/_static/logo.png _static/
- home:~/tmp/sampledoc> ls _static/ _templates/
- _static/:
- basic_screenshot.png default.css logo.png
-
- _templates/:
- layout.html
-
-Sphinx will automatically pick up the css and layout html files since
-we put them in the default places with the default names, but we have
-to manually include the logo in our :file:`layout.html`. Let's take a
-look at the layout file: the first part puts a horizontal navigation
-bar at the top of our page, like you see on the `sphinx
-<http://sphinx.pocoo.org>`_ and `matplotlib
-<http://matplotlib.sourceforge.net/>`_ sites, the second part includes
-a logo that when we click on it will take us `home` and the last part
-moves the vertical navigation panels to the right side of the page::
-
- {% extends "!layout.html" %}
-
-
- {% block rootrellink %}
- <li><a href="{{ pathto('index') }}">home</a>| </li>
- <li><a href="{{ pathto('search') }}">search</a>| </li>
- <li><a href="{{ pathto('contents') }}">documentation </a> »</li>
- {% endblock %}
-
-
- {% block relbar1 %}
-
- <div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">
- <a href="{{ pathto('index') }}"><img src="{{
- pathto("_static/logo.png", 1) }}" border="0" alt="sampledoc"/></a>
- </div>
- {{ super() }}
- {% endblock %}
-
- {# put the sidebar before the body #}
- {% block sidebar1 %}{{ sidebar() }}{% endblock %}
- {% block sidebar2 %}{% endblock %}
-
-Once you rebuild the site with a ``make html`` and reload the page in your browser, you should see a fancier site that looks like this
-
-.. image:: _static/fancy_screenshot.png
Deleted: trunk/py4science/examples/sphinx_qs/emacs_help.rst
===================================================================
--- trunk/py4science/examples/sphinx_qs/emacs_help.rst 2009-08-11 12:06:06 UTC (rev 7465)
+++ trunk/py4science/examples/sphinx_qs/emacs_help.rst 2009-08-11 12:07:15 UTC (rev 7466)
@@ -1,40 +0,0 @@
-.. _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
-
Deleted: trunk/py4science/examples/sphinx_qs/extensions.rst
===================================================================
--- trunk/py4science/examples/sphinx_qs/extensions.rst 2009-08-11 12:06:06 UTC (rev 7465)
+++ trunk/py4science/examples/sphinx_qs/extensions.rst 2009-08-11 12:07:15 UTC (rev 7466)
@@ -1,154 +0,0 @@
-.. _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:`fetching-the-data`, and install them in
-our :file:`sampledoc` project :file:`sphinxext` directory::
-
- home:~/tmp/sampledoc> mkdir sphinxext
- home:~/tmp/sampledoc> cp ../sampledoc_tut/sphinxext/*.py sphinxext/
- home:~/tmp/sampledoc> 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:`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/ellipses.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
-
-
-.. _extensions-literal:
-
-This file
-=========
-
-.. literalinclude:: extensions.rst
-
-
Deleted: trunk/py4science/examples/sphinx_qs/getting_started.rst
===================================================================
--- trunk/py4science/examples/sphinx_qs/getting_started.rst 2009-08-11 12:06:06 UTC (rev 7465)
+++ trunk/py4science/examples/sphinx_qs/getting_started.rst 2009-08-11 12:07:15 UTC (rev 7466)
@@ -1,105 +0,0 @@
-.. _getting_started:
-
-
-***************
-Getting started
-***************
-
-.. _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 "sampledoc" as the name of my
-project. cd into your new directory and check the contents::
-
- home:~/tmp/sampledoc> ls
- Makefile _static conf.py
- _build _templates index.rst
-
-The index.rst is the master ReST for your project, but before adding
-anything, let's see if we can build some html::
-
- make html
-
-If you now point your browser to :file:`_build/html/index.html`, you
-should see a basic spinx site.
-
-.. image:: _static/basic_screenshot.png
-
-.. _fetching-the-data:
-
-Fetching the data
------------------
-
-Now we will start to customize out docs. Grab a couple of files from
-the `web site
-<http://matplotlib.svn.sourceforge.net/viewvc/matplotlib/trunk/sampledoc_tut/>`_
-or svn. You will need :file:`getting_started.rst` and
-:file:`_static/basic_screenshot.png`. All of the files live in the
-"completed" version of this tutorial, but since this is a tutorial,
-we'll just grab them one at a time, so you can learn what needs to be
-changed where. Since we have more files to come, I'm going to grab
-the whole svn directory and just copy the files I need over for now.
-First, I'll cd to the directory containing my project, and get the
-"finished" product, and then copy in just the files I need::
-
- home:~/tmp/sampledoc> pwd
- /Users/jdhunter/tmp/sampledoc
- home:~/tmp/sampledoc> cd ..
- home:~/tmp> svn co
- https://matplotlib.svn.sourceforge.net/svnroot/matplotlib/trunk/\
- sampledoc_tut
- A sampledoc_tut/cheatsheet.rst
- A sampledoc_tut/_static
- A sampledoc_tut/_static/basic_screenshot.png
- A sampledoc_tut/conf.py
- A sampledoc_tut/Makefile
- A sampledoc_tut/_templates
- A sampledoc_tut/_build
- A sampledoc_tut/getting_started.rst
- A sampledoc_tut/index.rst
- Checked out revision 7449.
- home:~/tmp> cp sampledoc_tut/getting_started.rst sampledoc/
- home:~/tmp> cp sampledoc_tut/_static/basic_screenshot.png sampledoc/_static/
-
-Now we are ready to rebuild the docs. We used the image directory to
-include to the screenshot above with::
-
- .. image:: _static/basic_screenshot.png
-
-The last step is to modify :file:`index.rst` to include the
-getting_started file (be careful with the indentation, the
-"getting_started" should line up with the ':' in ``:maxdepth``::
-
- Contents:
-
- .. toctree::
- :maxdepth: 2
-
- getting_started.rst
-
-and then rebuild the docs with ``make html``. When you reload the
-page, you should see a link to the "Getting Started" docs, and in
-there this page with the screenshot. `Voila!`
-
-
-Next we'll customize the look and feel of our site to give it a logo,
-some custom css, and update the navigation panels to look more like
-the `sphinx <http://sphinx.pocoo.org/>`_ site itself -- see
-:ref:`custom_look`.
-
Deleted: trunk/py4science/examples/sphinx_qs/index.rst
===================================================================
--- trunk/py4science/examples/sphinx_qs/index.rst 2009-08-11 12:06:06 UTC (rev 7465)
+++ trunk/py4science/examples/sphinx_qs/index.rst 2009-08-11 12:07:15 UTC (rev 7466)
@@ -1,35 +0,0 @@
-.. sampledoc documentation master file, created by
- sphinx-quickstart on Tue Aug 11 05:04:40 2009.
- You can adapt this file completely to your liking, but it should at least
- contain the root `toctree` directive.
-
-sampledoc tutorial
-==================
-
-This is a tutorial introduction to quickly get you up and running with
-your own sphinx documentation system. We'll cover everything from
-installing sphinx, to customizing the look and feel, to using custom
-extensions for embedding plots, inheritance diagrams, syntax
-highlighted ipython sessions and more. If you follow along the
-tutorial, you'll start with nothing and end up with this site! The
-source code for this tutorial lives in mpl svn (see
-:ref:`fetching-the-data`)
-
-Contents:
-
-.. toctree::
- :maxdepth: 2
-
- getting_started.rst
- custom_look.rst
- extensions.rst
- cheatsheet.rst
- emacs_help.rst
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
