Docs refactor

Branch: reorganize-docs

With pytest 3.0 the aim is to refactor the documentation to make it more accessible. Central concepts:

• Some docs for specific audiences
• One topic per page
• Complete and improve reference pages, maybe by expanding docstrings (what is a testitem?)

Process

Docs are automatically built on commit and hosted at http://pytest.readthedocs.io/en/latest/

pip install -r requirements-docs.txt

make html uses sphinx to build locally

A tool called regendoc runs the examples and ensure their output is correct (??)

Sections

• Documentation by audience
  • Minimal examples
• Front page:
  • What is pytest?
  • Installation
  • FOSS license Side bar links:
  • Talks, links
  • Plugin index
  • Link to repo
  • Link to blog/planet
  • Link to pypi?
  • Getting help (contact channels, stack overflow)
• Reference (auto generated?)
• Examples

Personas

(Basic) user: Experienced with Python, new to pytest. May be new to testing. Keep these topics to a minimum to make getting started approachable and not daunting.

Advanced user: Experienced with basic pytest usages. More topics around maintaining a test suite.

Plugin author: Writing a plugin that would be published and may be used by others.

Contributor: Someone who may contribute to the pytest project.

Questions

• How to invite more people to contribute and coordinate well?
• How to make sure no existing content is lost in transfer/reorg?