docs warnings as errors and initial page similar to README

* Changed "index" to be more similar to the README (#1708).
* Fixes numerous issues like missing documents, syntax errors, etc (#1829, #432).
* Mention all docs in "contents.rst" so it's easier for users to locate (#1112).
* Add doc generation and checking to Travis and AppVeyor, to avoid re-introducing errors.

Fixes #432, Fixes #1112, Fixes #1708, Fixes #1829

Author: nicoddemus

.travis.yml

@@ -26,6 +26,7 @@ env:
     - TESTENV=py27-nobyte
     - TESTENV=doctesting
     - TESTENV=freeze
+    - TESTENV=docs
 
 script: tox --recreate -e $TESTENV
 

README.rst

@@ -52,7 +52,7 @@ To execute it::
     ======= 1 failed in 0.12 seconds ========
 
 
-Due to ``py.test``'s detailed assertion introspection, only plain ``assert`` statements are used. See `getting-started <http://docs.pytest.org/en/latest/getting-started.html#our-first-test-run>`_ for more examples.
+Due to ``pytest``'s detailed assertion introspection, only plain ``assert`` statements are used. See `getting-started <http://docs.pytest.org/en/latest/getting-started.html#our-first-test-run>`_ for more examples.
 
 
 Features

_pytest/python.py

@@ -711,31 +711,26 @@ class Metafunc(fixtures.FuncargnamesCompatAttr):
     They help to inspect a test function and to generate tests according to
     test configuration or values specified in the class or module where a
     test function is defined.
-
-    :ivar fixturenames: set of fixture names required by the test function
-
-    :ivar function: underlying python test function
-
-    :ivar cls: class object where the test function is defined in or ``None``.
-
-    :ivar module: the module object where the test function is defined in.
-
-    :ivar config: access to the :class:`_pytest.config.Config` object for the
-        test session.
-
-    :ivar funcargnames:
-        .. deprecated:: 2.3
-            Use ``fixturenames`` instead.
     """
     def __init__(self, function, fixtureinfo, config, cls=None, module=None):
+        #: access to the :class:`_pytest.config.Config` object for the test session
         self.config = config
+
+        #: the module object where the test function is defined in.
         self.module = module
+
+        #: underlying python test function
         self.function = function
+
+        #: set of fixture names required by the test function
         self.fixturenames = fixtureinfo.names_closure
-        self._arg2fixturedefs = fixtureinfo.name2fixturedefs
+
+        #: class object where the test function is defined in or ``None``.
         self.cls = cls
+
         self._calls = []
         self._ids = py.builtin.set()
+        self._arg2fixturedefs = fixtureinfo.name2fixturedefs
 
     def parametrize(self, argnames, argvalues, indirect=False, ids=None,
         scope=None):

appveyor.yml

@@ -10,7 +10,7 @@ environment:
   # builds timing out in AppVeyor
   - TOXENV: "linting,py26,py27,py33,py34,py35,pypy"
   - TOXENV: "py27-pexpect,py27-xdist,py27-trial,py35-pexpect,py35-xdist,py35-trial"
-  - TOXENV: "py27-nobyte,doctesting,freeze"
+  - TOXENV: "py27-nobyte,doctesting,freeze,docs"
 
 install:
   - echo Installed Pythons

doc/en/adopt.rst

@@ -1,3 +1,4 @@
+:orphan:
 
 April 2015 is "adopt pytest month"
 =============================================

doc/en/announce/release-2.9.1.rst

@@ -63,3 +63,5 @@ The py.test Development Team
 .. _#649: https://github.com/pytest-dev/pytest/issues/649
 
 .. _@asottile: https://github.com/asottile
+.. _@nicoddemus: https://github.com/nicoddemus
+.. _@tomviner: https://github.com/tomviner

doc/en/announce/release-2.9.2.rst

@@ -69,5 +69,10 @@ The py.test Development Team
 .. _#1496: https://github.com/pytest-dev/pytest/issue/1496
 .. _#1524: https://github.com/pytest-dev/pytest/issue/1524
 
-.. _@prusse-martin: https://github.com/prusse-martin
 .. _@astraw38: https://github.com/astraw38
+.. _@hackebrot: https://github.com/hackebrot
+.. _@omarkohl: https://github.com/omarkohl
+.. _@pquentin: https://github.com/pquentin
+.. _@prusse-martin: https://github.com/prusse-martin
+.. _@RonnyPfannschmidt: https://github.com/RonnyPfannschmidt
+.. _@tomviner: https://github.com/tomviner

doc/en/announce/sprint2016.rst

@@ -39,8 +39,6 @@ Over 20 participants took part from 4 continents, including employees
 from Splunk, Personalkollen, Cobe.io, FanDuel and Dolby. Some newcomers
 mixed with developers who have worked on pytest since its beginning, and
 of course everyone in between.
-    Ana Ribeiro, Brazil
-    Ronny Pfannschmidt, Germany 
 
 
 Sprint organisation, schedule

doc/en/assert.rst

@@ -208,6 +208,7 @@ It is possible to add your own detailed explanations by implementing
 the ``pytest_assertrepr_compare`` hook.
 
 .. autofunction:: _pytest.hookspec.pytest_assertrepr_compare
+   :noindex:
 
 As an example consider adding the following hook in a conftest.py which
 provides an alternative explanation for ``Foo`` objects::

doc/en/builtin.rst

@@ -58,13 +58,13 @@ Fixtures and requests
 
 To mark a fixture function:
 
-.. autofunction:: _pytest.python.fixture
+.. autofunction:: _pytest.fixtures.fixture
 
 Tutorial at :ref:`fixtures`.
 
 The ``request`` object that can be used from fixture functions.
 
-.. autoclass:: _pytest.python.FixtureRequest()
+.. autoclass:: _pytest.fixtures.FixtureRequest()
     :members:
 
 

doc/en/conf.py

@@ -127,7 +127,7 @@
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-html_title = None
+html_title = 'pytest documentation'
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
 html_short_title = "pytest-%s" % release
@@ -144,7 +144,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.

doc/en/contents.rst

@@ -10,32 +10,51 @@ Full pytest documentation
 .. toctree::
    :maxdepth: 2
 
-   overview
-   apiref
-   example/index
+   getting-started
+   usage
+   assert
+   builtin
+   fixture
    monkeypatch
    tmpdir
    capture
    recwarn
+   doctest
+   mark
+   skipping
+   parametrize
    cache
-   plugins
+   unittest
    nose
+   xunit_setup
+   plugins
+   writing_plugins
+
+   example/index
+   goodpractices
+   customize
+   bash-completion
 
    backwards-compatibility
+   license
    contributing
    talks
+   projects
+   faq
+   contact
 
 .. only:: html
 
    .. toctree::
+      :maxdepth: 1
 
-      funcarg_compare
       announce/index
 
 .. only:: html
 
    .. toctree::
       :hidden:
+      :maxdepth: 1
 
       changelog
 

doc/en/doctest.rst

@@ -16,6 +16,7 @@ from docstrings in all python modules (including regular
 python test modules)::
 
     pytest --doctest-modules
+
 You can make these changes permanent in your project by
 putting them into a pytest.ini file like this:
 

doc/en/example/reportingdemo.rst

@@ -7,11 +7,9 @@ Demo of Python failure reports with pytest
 Here is a nice run of several tens of failures
 and how ``pytest`` presents things (unfortunately
 not showing the nice colors here in the HTML that you
-get on the terminal - we are working on that):
+get on the terminal - we are working on that)::
 
-.. code-block:: python
-
-    assertion $ pytest failure_demo.py
+    $ pytest failure_demo.py
     ======= test session starts ========
     platform linux -- Python 3.5.2, pytest-3.0.0, py-1.4.31, pluggy-0.3.1
     rootdir: $REGENDOC_TMPDIR/assertion, inifile: