Docs refactor
Branch: reorganize-docs
Preview: http://pytest.readthedocs.io/en/reorganize-docs/new-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
- Actually get sphinx to build an index
- 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?
Documentation is crucial in understanding how software can be used to solve problems. The areas of interest and the best form to cover these topics can vary for different audiences.
The idea is to embrance this concept and re-organize the pytest docs accordingly. When a person visits the documentation he/she can identify with one or more of the following groups and jump to the according sub pages without using search.
An audience is a group of people who want to use and/or contribute to the project.
A beginner user is new pytest, testing or Python. It is important to give clear instructions on how to install pytest, how to write basic tests and how to run pytest against the tests.
Ideally this is done in a tutorial like style that provides easy-to-follow steps along with an explanation on what each of the steps does.
Documentation for a beginner users briefly explains why writing tests is important but then focuses on explaining core concepts of pytest, such as test discovery, assert statements and fixtures.
Advanced users are familiar with core concepts of pytest and feel comfortable writing parametrized tests using fixtures and/or markers. He/She is interested in using plugins, fixture scoping or sharing and other features that increase efficiency or flexibility such as hooks.
Guides for advanced users can be of different styles and vary from topic to topic. Comprehensive blog-post like articles or cookbook style like recipes explain how to combine several features based on real-world scenarios.
An advanced user may want to share useful functionality as a package on PyPI. The documentation for plugin authors follows the same principles as for advanced users.
He/She is introduced to cookiecutter-pytest-plugin as the most convenient
way to get started writing plugins. Other section describe how to set up entry
points via setuptools and might refer to use cases from existing plugins. Most
importantly it is explained how to write tests against plugin code.
Documentation for plugin author additionally covers how to move a plugin project to the pytest-dev organization on GitHub.
This is group is different from the other audiences in the sense that is not based on a persons experience with pytest. Everyone is welcome to help out and contributions are greatly appreciated.
It is explained how the project is organized and how to interact with other community members, but also how to set up a development environment for pytest and how to get started with using GitHub, ideally by referring to the official guides.
This section outlines requirements for submitting issues or pull requests to pytest core and covers best practices for working on the code base.
Throughout the documentation cross-references can be used to point a user to related topics. For instance a tutorial in the beginner section on fixtures can contain a note that links to a cookbook for advanced users that covers fixture scopes and ids.
Doing so will help users internalize concepts of pytest and connections between features. At the same time, when an advanced user feels like looking up basics again, they can do so by using the related links rather than search.
