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 (??)
- 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)
- User docs
- Assert statements
- Test naming conventions and discovery
- Test directory structure
- Asserting about exceptions with pytest.raises
- Using pytest.mark to group tests
- Skip and skipif marks
- xfail mark
- parametrize basics
- Fixture basics
- Fixture finalizers
- Monkeypatch fixture
- Most useful command-line options
- IDE integration
- Types of test results
- Stdout capturing
- What happens when you press Ctrl-C?
- Advanced user docs
- Plugin recommendations
- conftest.py
- .ini config
- Adding extra functionality to marks
- Advanced parametrize
- Defining fixture scope
- Parametrized fixtures
- Running tests in parallel
- Profiling slow tests
- Testing against multiple Python interpreters with Tox
- Continuous integration (CI) systems
- Test coverage
- Debugging
- Python warnings
- Logging
- Flaky tests
- Plugin author docs
- Get started with the Cookiecutter template
- Introduction to hooks
- Registering a plugin with pytest (setup.py)
- Recommended practice for publishing (moving to pytest-dev)
- Adding a command-line option
- Testing plugins
- Using the pytest cache
- Contributor docs
- Setting up a development environment
- Contribution suggestions
- Git branch guide
- Preparing a pull request
- Project organisation
- Pytest history
- Deprecation guidelines
- Projects that use pytest
- Reference (some auto generated?)
- Hooks
- pytest.* (pytest namespace)
- Magic variables (eg
pytestmark) - Command line options
- Built in fixture
- Examples
Pages under these sections should all have minimal examples. More extensive examples go into the 'Examples' section.
(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.
Especially for this section, aim to explain the context of the problem. Why do you care about this? When do you use it? Not just - what is the syntax.
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? Try to put redirects?
