Improving docs across core strategies

[rsokl]

While working on a tutorial for pycon, I found that a substantial part of my materials was simply explaining what the various strategies do... which is what docstrings are for, but I think that ours fall short.

I am a fan of NumPy-style docs where each function's parameters are clearly described – alongside their type annotations – and an example section follows. Among these qualities, I think including an examples section for each docstring has the biggest bang for its buck.

One issue with this is that the Core Strategies page may end up being pretty lengthy. Perhaps expanding the TOC to include the strategies would make it easier for users to navigate. These would be collapsable, so this wouldn't blow up the navigation pane.

[Zac-HD]

• I'd support adopting Numpy-style structured docstrings for our whole API, though examples are probably most useful for strategies. If we're doing this we should also investigate linters which can check for malformed docstrings.
• Too many strategies to add them all to the table of contents, but arranging them into sections for scalars, collections, etc (like in our tutorial) would probably be useful.

[rsokl]

but arranging them into sections for scalars, collections, etc (like in our tutorial) would probably be useful

I had been thinking this as well, but wasn't sure if restructuring the page itself was on the table. I think this is a great idea and that it makes it easier to get a bird's eye view of all the strategies

[Zac-HD]

Anything that doesn't break URLs is on the table 😁

(I've wanted to restructure to follow the four kinds of documentation for years, but doing it well - including redirects - is a lot of work and not at the top of my todo list. I'd be delighted if someone volunteered to do it though!)

[rsokl]

Anything that doesn't break URLs is on the table

That is what I was worried about when I suggested expanding the TOC rather than rearrange the strats. Rearranging strategies into scalars, collections, etc. would break URLs, right? E.g. in the tutorial I link to https://hypothesis.readthedocs.io/en/latest/data.html#hypothesis.strategies.fixed_dictionaries

[Zac-HD]

Yeah, we can rearrange them on the page and add sidebar-linkable subheadings though (which also preserves ctrl-f searchability).

[epgui]

FWIW, this format of documentation is very easy to use for libraries that are essentially just a big collection of utility functions: https://ramdajs.com/docs/

The toolz library is also quite easy to navigate: https://toolz.readthedocs.io/en/latest/api.html