How-to guides

[jtrakk]

"What nobody tells you about documentation" distinguishes four types of documentation:

• tutorials,
• how-to guides,
• explanation,
• reference.

Of these, Trio docs are weakest on the "how-to guides" section. Currently there are a lot of hidden gems in chat, gists, and issues. That may be because Trio's evolving too quickly to have a stable set of how-tos. But as the API settles it would be nice to have vetted answers to common "how do I ___?" situations.

Even before 1.0 it would be nice to display the current status of each how-to so I don't have to keep track of the mental bookmarks I've saved for each task, and ask on chat to makes sure the 2-year-old gist is still the preferred way.

Also nice: having recommendations tested in CI so they don't fall out of date.

That includes how-tos which may involve third-party libraries, like triopg or asyncssh.

Some examples include: "How do I"...

• make line streams
• crawl the web
• schedule jobs
• make a Trionic process-pool executor
• interact with a repl, pexpect-style
• and many more...

[njsmith]

I think this is a duplicate of #472?

[jtrakk]

Yep.

[njsmith]

BTW, that was also inspired by that post – it's a pretty good post, isn't it? :-)

If you have a minute, it'd be great if you could check #472 and make sure all your ideas for howto topics are captured there – we don't want to lose those!

[N-Coder]

I'd be interested in seeing the example for "interact with a repl, pexpect-style", but couldn't find anything in the other issue.