From e7c8fc7db9b02921889ddc8ec1b930ec95991661 Mon Sep 17 00:00:00 2001 From: holger krekel Date: Wed, 6 Jul 2011 20:21:59 +0200 Subject: [PATCH] rearrange and streamline documentation navigation to better work with readthedocs and also with PDF generation. --- CHANGELOG | 3 +- doc/_static/sphinxdoc.css | 2 +- doc/_templates/indexsidebar.html | 2 +- doc/_templates/layout.html | 24 ----------- doc/_templates/localtoc.html | 37 +++++++++++++++++ doc/_templates/searchbox.html | 0 doc/conf.py | 12 +++--- doc/contents.txt | 33 ---------------- doc/example/index.txt | 4 ++ doc/features.txt | 57 ++++++++++++++++++++++++++ doc/index.txt | 68 +++++++------------------------- doc/overview.txt | 1 + 12 files changed, 124 insertions(+), 119 deletions(-) create mode 100644 doc/_templates/localtoc.html create mode 100644 doc/_templates/searchbox.html delete mode 100644 doc/contents.txt create mode 100644 doc/features.txt diff --git a/CHANGELOG b/CHANGELOG index 9328242b1..8221625f7 100644 --- a/CHANGELOG +++ b/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 ---------------------------------------------- diff --git a/doc/_static/sphinxdoc.css b/doc/_static/sphinxdoc.css index 02b940b0c..ab8ab5dce 100644 --- a/doc/_static/sphinxdoc.css +++ b/doc/_static/sphinxdoc.css @@ -48,7 +48,7 @@ div.body { } div.related { - font-size: 1em; + font-size: 0.8em; } div.related ul { diff --git a/doc/_templates/indexsidebar.html b/doc/_templates/indexsidebar.html index 17f9e0bbf..13d69cbd5 100644 --- a/doc/_templates/indexsidebar.html +++ b/doc/_templates/indexsidebar.html @@ -10,7 +10,7 @@

{{ release }} release [Changelog]

-pytest on PyPI +pytest/PyPI 

easy_install pytest
pip install pytest
diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html index d0ba098d9..14f15fc02 100644 --- a/doc/_templates/layout.html +++ b/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 %} -
-

pytest: rapid no-boilerplate testing with Python

-
- home |  - all docs |  - install |  - examples |  - customize |  - issues|  - contact  -
-
-{% endblock %} {% block footer %} {{ super() }} diff --git a/doc/_templates/localtoc.html b/doc/_templates/localtoc.html new file mode 100644 index 000000000..d08e0b720 --- /dev/null +++ b/doc/_templates/localtoc.html @@ -0,0 +1,37 @@ + +{%- if pagename != "search" %} + + +{%- endif %} + +

quicklinks

+
+ + +
+ index + + features +
+ install + + changelog +
+ examples + + customize +
+ issues[bb] + + contact +
+
+{% extends "basic/localtoc.html" %} + diff --git a/doc/_templates/searchbox.html b/doc/_templates/searchbox.html new file mode 100644 index 000000000..e69de29bb diff --git a/doc/conf.py b/doc/conf.py index 3c24de953..87fcca639 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -107,10 +107,10 @@ html_theme_options = {} # The name for this set of Sphinx documents. If None, it defaults to # " v 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 diff --git a/doc/contents.txt b/doc/contents.txt deleted file mode 100644 index a2f09a3d6..000000000 --- a/doc/contents.txt +++ /dev/null @@ -1,33 +0,0 @@ - -.. _toc: - -Table of Contents -======================== - -.. note:: - version 2.0 introduces :ref:`pytest as the main Python import name ` - -.. 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` diff --git a/doc/example/index.txt b/doc/example/index.txt index 15aa358b5..7cfa45c83 100644 --- a/doc/example/index.txt +++ b/doc/example/index.txt @@ -7,6 +7,10 @@ Usages and Examples Here is a (growing) list of examples. :ref:`Contact ` us if you need more examples or have questions. Also take a look at the :ref:`comprehensive documentation ` which contains many example snippets as well. +.. note:: + + see :doc:`../getting-started` for basic introductionary examples + .. toctree:: :maxdepth: 2 diff --git a/doc/features.txt b/doc/features.txt new file mode 100644 index 000000000..6f6aba490 --- /dev/null +++ b/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 `_ + - used in :ref:`many projects and organisations `, in test + suites ranging from 10 to 10s of thousands of tests + - has :ref:`comprehensive documentation ` + - comes with :ref:`tested examples ` + - supports :ref:`good integration practises ` + +- **provides no-boilerplate testing** + + - makes it :ref:`easy to get started `, + - refined :ref:`usage options ` + - :ref:`assert with the assert statement` + - helpful :ref:`traceback and failing assertion reporting ` + - allows :ref:`print debugging ` and :ref:`the + capturing of standard output during test execution ` + - 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 ` + - can :ref:`distribute tests to multiple CPUs ` through :ref:`xdist plugin ` + - can :ref:`continuously re-run failing tests ` + - many :ref:`builtin helpers ` + - flexible :ref:`Python test discovery` + - unique :ref:`dependency injection through funcargs ` + - :ref:`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 ` + - 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 + + diff --git a/doc/index.txt b/doc/index.txt index 57c0d446b..dc09b8e9c 100644 --- a/doc/index.txt +++ b/doc/index.txt @@ -1,62 +1,24 @@ +.. _toc: -Welcome to ``py.test``! -============================================= +Table of Contents +======================== +.. toctree:: + :maxdepth: 2 -- **a mature full-featured testing tool** - - - runs on Posix/Windows, Python 2.4-3.2, PyPy and Jython - - continuously `tested on many Python interpreters `_ - - used in :ref:`many projects and organisations `, in test - suites ranging from 10 to 10s of thousands of tests - - has :ref:`comprehensive documentation ` - - comes with :ref:`tested examples ` - - supports :ref:`good integration practises ` - -- **provides no-boilerplate testing** - - - makes it :ref:`easy to get started `, - - refined :ref:`usage options ` - - :ref:`assert with the assert statement` - - helpful :ref:`traceback and failing assertion reporting ` - - allows :ref:`print debugging ` and :ref:`the - capturing of standard output during test execution ` - - 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 ` - - can :ref:`distribute tests to multiple CPUs ` through :ref:`xdist plugin ` - - can :ref:`continuously re-run failing tests ` - - many :ref:`builtin helpers ` - - flexible :ref:`Python test discovery` - - unique :ref:`dependency injection through funcargs ` - - :ref:`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 ` - - 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 + overview + example/index + apiref + plugins + talks + develop + announce/index .. toctree:: :hidden: - contact.txt - contents.txt + changelog.txt + naming20.txt + example/attic diff --git a/doc/overview.txt b/doc/overview.txt index 0743f088e..ccdd40791 100644 --- a/doc/overview.txt +++ b/doc/overview.txt @@ -5,6 +5,7 @@ Getting started basics .. toctree:: :maxdepth: 2 + features.txt getting-started.txt usage.txt goodpractises.txt