Skip to content

Commit

Permalink
fix broken link on homepage
Browse files Browse the repository at this point in the history 
svn path=/trunk/sampledoc_tut/; revision=8832
  • Loading branch information
@jdh2358
jdh2358 committed Dec 13, 2010
1 parent a546780 commit 8a47841
Show file tree
Hide file tree
Showing 4 changed files with 146 additions and 122 deletions.
1 change: 0 additions & 1 deletion _templates/layout.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@
{% block rootrellink %}
<li><a href="{{ pathto('index') }}">home</a>|&nbsp;</li>
<li><a href="{{ pathto('search') }}">search</a>|&nbsp;</li>
<li><a href="{{ pathto('contents') }}">documentation </a> &raquo;</li>
{% endblock %}


Expand Down
12 changes: 6 additions & 6 deletions extensions.rst
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
.. _extensions:

<

****************************************************
Sphinx extensions for embedded plots, math and more
Expand All @@ -19,9 +19,8 @@ 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
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
Expand All @@ -41,16 +40,17 @@ 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',
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`.

Expand Down
226 changes: 113 additions & 113 deletions getting_started.rst
View file
Original file line number Diff line number Diff line change
@@ -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`.

29 changes: 27 additions & 2 deletions ipython_directive.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,16 @@ sphinx documents. It knows about standard ipython prompts, and
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::

Expand All @@ -18,6 +27,16 @@ well.
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
Expand Down Expand Up @@ -261,4 +280,10 @@ line just below them (eg ``savefig``).
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

0 comments on commit 8a47841

Please sign in to comment.