rearrange and streamline documentation navigation to better work

with readthedocs and also with PDF generation.

CHANGELOG

@@ -13,7 +13,8 @@ Changes between 2.0.3 and 2.1.0.DEV
 - fix issue48: typo in MarkInfo repr leading to exception
 - fix issue49: avoid confusing error when initizaliation partially fails
 - fix issue44: env/username expansion for junitxml file path
-- show releaselevel information for pypy
+- show releaselevel information in test runs for pypy
+- reworked doc pages for better navigation and PDF generation
 
 Changes between 2.0.2 and 2.0.3
 ----------------------------------------------

doc/_static/sphinxdoc.css

@@ -48,7 +48,7 @@ div.body {
 }
 
 div.related {
-    font-size: 1em;
+    font-size: 0.8em;
 }
 
 div.related ul {

doc/_templates/indexsidebar.html

@@ -10,7 +10,7 @@
 <p><b><a href="{{ pathto('announce/index')}}">{{ release }} release</a></b>
 [<a href="{{ pathto('changelog') }}">Changelog</a>]</p>
 <p>
-<a href="http://pypi.python.org/pypi/pytest">pytest on PyPI</a>
+<a href="http://pypi.python.org/pypi/pytest">pytest/PyPI</a>
 </p>
 <pre>easy_install pytest</pre>
 <pre>pip install pytest</pre>

doc/_templates/layout.html

@@ -1,29 +1,5 @@
 {% extends "!layout.html" %}
 
-{% block relbar1 %}
-{% endblock %}
-{% block relbar2 %}
-{% endblock %}
-
-{% block rootrellink %}
-{% endblock %}
-{% block sidebarrel %}
-{% endblock %}
-
-{% block header %}
-<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">
-    <h1>pytest: rapid no-boilerplate testing with Python</h1>
-    <div style="text-align: left; font-size: 130%; vertical-align: middle;">
-            <a href="{{ pathto('index') }}">home</a>&nbsp;|&nbsp;
-            <a href="{{ pathto('contents') }}">all docs</a>&nbsp;|&nbsp;
-            <a href="{{ pathto('getting-started') }}">install</a>&nbsp;|&nbsp;
-            <a href="{{ pathto('example/index') }}">examples</a>&nbsp;|&nbsp;
-            <a href="{{ pathto('customize') }}">customize</a>&nbsp;|&nbsp;
-            <a href="https://bitbucket.org/hpk42/pytest/issues?status=new&status=open">issues</a>|&nbsp;
-            <a href="{{ pathto('contact') }}">contact</a>&nbsp;
-    </div>
-</div>
-{% endblock %}
 
 {% block footer %}
 {{ super() }}

doc/_templates/localtoc.html

@@ -0,0 +1,37 @@
+
+{%- if pagename != "search" %}
+<div id="searchbox" style="display: none">
+    <form class="search" action="{{ pathto('search') }}" method="get">
+      <input type="text" name="q" size="18" />
+      <input type="submit" value="{{ _('Search') }}" />
+      <input type="hidden" name="check_keywords" value="yes" />
+      <input type="hidden" name="area" value="default" />
+    </form>
+</div>
+<script type="text/javascript">$('#searchbox').show(0);</script>
+{%- endif %}
+
+<h3>quicklinks</h3>
+<div style="text-align: left; font-size: 100%; vertical-align: middle;">
+<table>
+<tr>
+<td>
+        <a href="{{ pathto('index') }}">index</a>
+</td><td>
+        <a href="{{ pathto('features') }}">features</a>
+</td></tr><tr><td>
+        <a href="{{ pathto('getting-started') }}">install</a>
+</td><td>
+        <a href="{{ pathto('changelog') }}">changelog</a>
+</td></tr><tr><td>
+        <a href="{{ pathto('example/index') }}">examples</a>
+</td><td>
+        <a href="{{ pathto('customize') }}">customize</a>
+</td></tr><tr><td>
+        <a href="https://bitbucket.org/hpk42/pytest/issues?status=new&status=open">issues[bb]</a>
+</td><td>
+        <a href="{{ pathto('contact') }}">contact</a>
+</td></tr></table>
+</div>
+{% extends "basic/localtoc.html" %}
+

doc/conf.py

@@ -107,10 +107,10 @@ html_theme_options = {}
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-#html_title = None
+html_title = None
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
-#html_short_title = None
+html_short_title = "pytest-%s" % release
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
@@ -136,7 +136,7 @@ html_static_path = ['_static']
 
 # Custom sidebar templates, maps document names to template names.
 #html_sidebars = {}
-html_sidebars = {'index': 'indexsidebar.html'}
+#html_sidebars = {'*': 'sidebar.html'}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
@@ -145,16 +145,16 @@ html_sidebars = {'index': 'indexsidebar.html'}
 
 
 # If false, no module index is generated.
-#html_domain_indices = True
+html_domain_indices = True
 
 # If false, no index is generated.
-#html_use_index = True
+html_use_index = False
 
 # If true, the index is split into individual pages for each letter.
 #html_split_index = False
 
 # If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
+html_show_sourcelink = False
 
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
 #html_show_sphinx = True

doc/contents.txt

@@ -1,33 +0,0 @@
-
-.. _toc:
-
-Table of Contents
-========================
-
-.. note::
-   version 2.0 introduces :ref:`pytest as the main Python import name <naming20>`
-
-.. toctree::
-   :maxdepth: 2
-
-   overview
-   apiref
-   plugins
-   example/index
-   talks
-   develop
-   announce/index
-
-.. toctree::
-   :hidden:
-
-   changelog.txt
-   naming20.txt
-   example/attic
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`

doc/example/index.txt

@@ -7,6 +7,10 @@ Usages and Examples
 Here is a (growing) list of examples. :ref:`Contact <contact>` us if you
 need more examples or have questions. Also take a look at the :ref:`comprehensive documentation <toc>` which contains many example snippets as well.
 
+.. note::
+
+   see :doc:`../getting-started` for basic introductionary examples
+
 .. toctree::
    :maxdepth: 2
 

doc/features.txt

@@ -0,0 +1,57 @@
+
+
+Feature Overview
+=============================================
+
+
+- **a mature full-featured testing tool**
+
+ - runs on Posix/Windows, Python 2.4-3.2, PyPy and Jython
+ - continuously `tested on many Python interpreters <http://hudson.testrun.org/view/pytest/job/pytest/>`_
+ - used in :ref:`many projects and organisations <projects>`, in test
+   suites ranging from 10 to 10s of thousands of tests
+ - has :ref:`comprehensive documentation <toc>`
+ - comes with :ref:`tested examples <examples>`
+ - supports :ref:`good integration practises <goodpractises>`
+
+- **provides no-boilerplate testing**
+
+ - makes it :ref:`easy to get started <getstarted>`,
+ - refined :ref:`usage options <usage>`
+ - :ref:`assert with the assert statement`
+ - helpful :ref:`traceback and failing assertion reporting <tbreportdemo>`
+ - allows :ref:`print debugging <printdebugging>` and :ref:`the
+   capturing of standard output during test execution <captures>`
+ - supports :pep:`8` compliant coding styles in tests
+
+- **supports functional testing and complex test setups**
+
+ - advanced :ref:`skip and xfail`
+ - generic :ref:`marking and test selection <mark>`
+ - can :ref:`distribute tests to multiple CPUs <xdistcpu>` through :ref:`xdist plugin <xdist>`
+ - can :ref:`continuously re-run failing tests <looponfailing>`
+ - many :ref:`builtin helpers <pytest helpers>`
+ - flexible :ref:`Python test discovery`
+ - unique :ref:`dependency injection through funcargs <funcargs>`
+ - :ref:`parametrized test functions <parametrized test functions>`
+
+- **integrates many common testing methods**
+
+ - can integrate ``nose``, ``unittest.py`` and ``doctest.py`` style
+   tests, including running testcases made for Django and trial
+ - supports extended :ref:`xUnit style setup <xunitsetup>`
+ - supports domain-specific :ref:`non-python tests`
+ - supports the generation of testing coverage reports
+ - `Javascript unit- and functional testing`_
+
+- **extensive plugin and customization system**
+
+ - all collection, reporting, running aspects are delegated to hook functions
+ - customizations can be per-directory, per-project or per PyPI released plugins
+ - it is easy to add command line options or do other kind of add-ons and customizations.
+
+.. _`Javascript unit- and functional testing`: http://pypi.python.org/pypi/oejskit
+
+.. _`easy`: http://bruynooghe.blogspot.com/2009/12/skipping-slow-test-by-default-in-pytest.html
+
+

doc/index.txt

@@ -1,62 +1,24 @@
 
+.. _toc:
 
-Welcome to ``py.test``!
+Table of Contents
-=============================================
+========================
 
+.. toctree::
+   :maxdepth: 2
 
-- **a mature full-featured testing tool**
+   overview
-
+   example/index
- - runs on Posix/Windows, Python 2.4-3.2, PyPy and Jython
+   apiref
- - continuously `tested on many Python interpreters <http://hudson.testrun.org/view/pytest/job/pytest/>`_
+   plugins
- - used in :ref:`many projects and organisations <projects>`, in test
+   talks
-   suites ranging from 10 to 10s of thousands of tests
+   develop
- - has :ref:`comprehensive documentation <toc>`
+   announce/index
- - comes with :ref:`tested examples <examples>`
- - supports :ref:`good integration practises <goodpractises>`
-
-- **provides no-boilerplate testing**
-
- - makes it :ref:`easy to get started <getstarted>`,
- - refined :ref:`usage options <usage>`
- - :ref:`assert with the assert statement`
- - helpful :ref:`traceback and failing assertion reporting <tbreportdemo>`
- - allows :ref:`print debugging <printdebugging>` and :ref:`the
-   capturing of standard output during test execution <captures>`
- - supports :pep:`8` compliant coding styles in tests
-
-- **supports functional testing and complex test setups**
-
- - advanced :ref:`skip and xfail`
- - generic :ref:`marking and test selection <mark>`
- - can :ref:`distribute tests to multiple CPUs <xdistcpu>` through :ref:`xdist plugin <xdist>`
- - can :ref:`continuously re-run failing tests <looponfailing>`
- - many :ref:`builtin helpers <pytest helpers>`
- - flexible :ref:`Python test discovery`
- - unique :ref:`dependency injection through funcargs <funcargs>`
- - :ref:`parametrized test functions <parametrized test functions>`
-
-- **integrates many common testing methods**
-
- - can integrate ``nose``, ``unittest.py`` and ``doctest.py`` style
-   tests, including running testcases made for Django and trial
- - supports extended :ref:`xUnit style setup <xunitsetup>`
- - supports domain-specific :ref:`non-python tests`
- - supports the generation of testing coverage reports
- - `Javascript unit- and functional testing`_
-
-- **extensive plugin and customization system**
-
- - all collection, reporting, running aspects are delegated to hook functions
- - customizations can be per-directory, per-project or per PyPI released plugins
- - it is easy to add command line options or do other kind of add-ons and customizations.
-
-.. _`Javascript unit- and functional testing`: http://pypi.python.org/pypi/oejskit
-
-.. _`easy`: http://bruynooghe.blogspot.com/2009/12/skipping-slow-test-by-default-in-pytest.html
 
 .. toctree::
    :hidden:
 
-   contact.txt
+   changelog.txt
-   contents.txt
+   naming20.txt
+   example/attic
 

doc/overview.txt

@@ -5,6 +5,7 @@ Getting started basics
 .. toctree::
    :maxdepth: 2
 
+   features.txt
    getting-started.txt
    usage.txt
    goodpractises.txt