Documentation overhaul
Author: Liam-DeVoeCreated Mar 18, 2025Updated Jul 31, 2026
Labelsmetadocs
This meta-level issue tracks our refactoring of the Hypothesis documentation to follow diataxis, and to generally improve our documentation.
- add tutorial pages
- phases
- database
- stateful (rewrite)
- "adding notes" (rewrite)
- deadline
- filter rewriting. Maybe fits better under "explanation"; the user isn't doing anything.
- add explanation pages
- "the lifetime of a hypothesis test" article + notes on the explain phase (scrutineer + inquisitor)
- "Hypothesis database keys", how a database key is computed, what uniqueness level you can (generally) rely on
- parametrization + test name + source code. Blank lines + decorators + comments are ignored
- choice sequence and spans (draft exists in liam's
docsbranch)- link to this from the
metadata.choice_nodesandmetadata.spansobservation docs, and throughout alternative backends
- link to this from the
- add howto pages
- "how to debug flaky tests"
- "how to come up with properties"
- "how to write efficient tests" (name tbd), about strategies overhead. Say that creating strategies per-test case (as with |st.data| and |st.composite|) can be slow. Particularly if the strategy can't be cached because its args are changing dynamically. Try rewriting to minimize the number of strategies you use, or increase cacheability.
- https://github.com/HypothesisWorks/hypothesis/pull/4341#issuecomment-2780252954
- https://github.com/HypothesisWorks/hypothesis/pull/4315#discussion_r2009197810
- refactor "inferred types" in the API reference to distribute amongst
st.builds,@given,register_type_strategy. And add a "working with types" tutorial or how-to - reword
settings.defaulthttps://github.com/HypothesisWorks/hypothesis/pull/4311#discussion_r2008627137 - consider numpy-style structured docstrings, especially for strategies (originally https://github.com/HypothesisWorks/hypothesis/issues/2957)
- document
.patchfile workflow with the pytest plugin https://github.com/HypothesisWorks/hypothesis/pull/3631 - https://github.com/HypothesisWorks/hypothesis/pull/4315#discussion_r2022111502
- https://github.com/HypothesisWorks/hypothesis/pull/4337#discussion_r2028053308
- https://github.com/HypothesisWorks/hypothesis/pull/4631#discussion_r3625268381
- https://github.com/HypothesisWorks/hypothesis/pull/4345#discussion_r2050001068
- figure out mechanics of redirects, possibly using https://github.com/documatt/sphinx-reredirects
- systematically categorize which url targets to redirect
- (^ done, but) might be worth redirecting popular url fragments on https://hypothesis.readthedocs.io/en/latest/details.html to the relevant
- improve
(dynamically calculated)docstrings for settings - stop shed from autoformatting code block examples to add newlines
- document .map and .flatmap as actual automethods on SearchStrategy, and link to them just like .filter
- merge testimonials into "projects that use hypothesis"? https://github.com/HypothesisWorks/hypothesis/pull/4340#discussion_r2029697693
Small stuff
- drop nose references, maybe test nose2 in CI? https://github.com/HypothesisWorks/hypothesis/pull/4341#discussion_r2030038791 place, like assume, target, random, type annotations, custom function execution, etc
- rework
target()example? https://github.com/HypothesisWorks/hypothesis/pull/4311#discussion_r2000565650 - add docs test for xps namespace? https://github.com/HypothesisWorks/hypothesis/pull/4311#discussion_r2006919629
- cmd+f
TODO_DOCS -
Verbosityvssettings.verbosity(+ same forPhase)
Source: HypothesisWorks/hypothesis