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?)
Docs are automatically built on commit and hosted at http://pytest.readthedocs.io/en/latest/
Docs are built using Sphinx and RST markup.
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 (??)
- 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
(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.
Add this line to the top of your file and then an index will be automatically generated:
.. index:: topic 1, topic 2, topic 3
- How to invite more people to contribute and coordinate well?
- How to make sure no existing content is lost in transfer/reorg?
- How to handle breaking links?
