Menu
▾
▴
SF.net SVN: matplotlib:[8832] trunk/sampledoc_tut
|
From: <jd...@us...> - 2010-12-13 15:52:44
|
Revision: 8832
http://matplotlib.svn.sourceforge.net/matplotlib/?rev=8832&view=rev
Author: jdh2358
Date: 2010-12-13 15:52:37 +0000 (Mon, 13 Dec 2010)
Log Message:
-----------
fix broken link on homepage
Modified Paths:
--------------
trunk/sampledoc_tut/_templates/layout.html
trunk/sampledoc_tut/extensions.rst
trunk/sampledoc_tut/getting_started.rst
trunk/sampledoc_tut/ipython_directive.rst
Modified: trunk/sampledoc_tut/_templates/layout.html
===================================================================
--- trunk/sampledoc_tut/_templates/layout.html 2010-12-13 15:51:13 UTC (rev 8831)
+++ trunk/sampledoc_tut/_templates/layout.html 2010-12-13 15:52:37 UTC (rev 8832)
@@ -4,7 +4,6 @@
{% 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 %}
Modified: trunk/sampledoc_tut/extensions.rst
===================================================================
--- trunk/sampledoc_tut/extensions.rst 2010-12-13 15:51:13 UTC (rev 8831)
+++ trunk/sampledoc_tut/extensions.rst 2010-12-13 15:52:37 UTC (rev 8832)
@@ -1,6 +1,6 @@
.. _extensions:
+<
-
****************************************************
Sphinx extensions for embedded plots, math and more
****************************************************
@@ -19,9 +19,8 @@
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
+ apigen.py docscrape_sphinx.py ipython_console_highlighting.py
+ docscrape.py inheritance_diagram.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
@@ -41,16 +40,17 @@
# 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',
+ extensions = [
+ 'matplotlib.sphinxext.mathmpl',
'matplotlib.sphinxext.only_directives',
'matplotlib.sphinxext.plot_directive',
+ 'matplotlib.sphinxext.ipython_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`.
Modified: trunk/sampledoc_tut/getting_started.rst
===================================================================
--- trunk/sampledoc_tut/getting_started.rst 2010-12-13 15:51:13 UTC (rev 8831)
+++ trunk/sampledoc_tut/getting_started.rst 2010-12-13 15:52:37 UTC (rev 8832)
@@ -1,113 +1,113 @@
-.. _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 sphinx 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 up back into the directory containing my project, check
-out the "finished" product from svn, and then copy in just the files I
-need into my :file:`sampledoc` directory::
-
- 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/
-
-The last step is to modify :file:`index.rst` to include the
-:file:`getting_started.rst` file (be careful with the indentation, the
-"g" in "getting_started" should line up with the ':' in ``:maxdepth``::
-
- Contents:
-
- .. toctree::
- :maxdepth: 2
-
- getting_started.rst
-
-and then rebuild the docs::
-
- cd sampledoc
- make html
-
-
-When you reload the page by refreshing your browser pointing to
-:file:`_build/html/index.html`, you should see a link to the
-"Getting Started" docs, and in there this page with the screenshot.
-`Voila!`
-
-Note we used the image directive to include to the screenshot above
-with::
-
- .. image:: _static/basic_screenshot.png
-
-
-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`.
-
+.. _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 -U 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 sphinx 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 up back into the directory containing my project, check
+out the "finished" product from svn, and then copy in just the files I
+need into my :file:`sampledoc` directory::
+
+ 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/
+
+The last step is to modify :file:`index.rst` to include the
+:file:`getting_started.rst` file (be careful with the indentation, the
+"g" in "getting_started" should line up with the ':' in ``:maxdepth``::
+
+ Contents:
+
+ .. toctree::
+ :maxdepth: 2
+
+ getting_started.rst
+
+and then rebuild the docs::
+
+ cd sampledoc
+ make html
+
+
+When you reload the page by refreshing your browser pointing to
+:file:`_build/html/index.html`, you should see a link to the
+"Getting Started" docs, and in there this page with the screenshot.
+`Voila!`
+
+Note we used the image directive to include to the screenshot above
+with::
+
+ .. image:: _static/basic_screenshot.png
+
+
+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`.
+
Modified: trunk/sampledoc_tut/ipython_directive.rst
===================================================================
--- trunk/sampledoc_tut/ipython_directive.rst 2010-12-13 15:51:13 UTC (rev 8831)
+++ trunk/sampledoc_tut/ipython_directive.rst 2010-12-13 15:52:37 UTC (rev 8832)
@@ -9,8 +9,17 @@
extracts the input and output lines. These prompts will be renumbered
starting at ``1``. The inputs will be fed to an embedded ipython
interpreter and the outputs from that interpreter will be inserted as
-well.
+well. For example, code blocks like the following::
+ .. ipython::
+
+ In [136]: x = 2
+
+ In [137]: x**3
+ Out[137]: 8
+
+will be rendered as
+
.. ipython::
In [136]: x = 2
@@ -18,6 +27,16 @@
In [137]: x**3
Out[137]: 8
+.. note::
+
+ This tutorial should be read side-by-side with the Sphinc source
+ for this document (see :ref:`ipython_literal`) because otherwise
+ you will see only the rendered output and not the code that
+ generated it. Excepting the example above, we will not in general
+ be showing the liuteral rest in this document that generates the
+ rendered output.
+
+
The state from previous sessions is stored, and standard error is
trapped. At doc build time, ipython's output and std err will be
inserted, and prompts will be renumbered. So the prompt below should
@@ -261,4 +280,10 @@
match. Also, can be applied to the entire ``..ipython`` block as a
directive option with ``:doctest:``.
-That's all folks!
+.. _ipython_literal:
+
+Sphinx source for this tutorial
+====================================
+
+.. literalinclude:: ipython_directive.rst
+
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
