jakkdl
commented
1 month ago For generating rules pages, I've looked at https://www.sphinx-doc.org/en/master/man/sphinx-autogen.html and https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html#directive-autosummary and considered making visitors classes with the extra documentation in their docstrings. But I think that's going to cause issues - primarily in having large limitations on the formatting of the resulting rules subpages. The page would essentially be the documentation of a single class, with code examples etc etc in the docstring.
The easiest would be manually writing the subpages, and that's probably what I'll start with for the sake of exploring layout etc etc, but this will be error-prone/cumbersome/hard to maintain. I think in the end I'll have to write a custom generating script, that reads the data from the visitor classes (means it has to be able to handle multiple codes per visitor) or an entirely separate system.
I'm thinking something like:
- Each visitor defines a set of methods that return (rst) strings, one method per section in the rules page, and each method takes the error code as an argument.
- e.g.
Visitor91x.documentation_examples('ASYNC910') - Might as well copy the sections from ruff + blurb:
documentation_blurb: for use in the overview table in rules.rst (equivalent to ruff "Message" column)documentation_trigger: describes what will trigger the rule (equivalent to what it does).documentation_info: longer explanation (why is this bad)documentation_examples: examples that trigger the error, and how to fix them. (example).- I'm somewhat tempted to source these directly from the
eval_files, but that'd hit problems with library-specific errors and all the special MagicMarkers. - But writing sections that are going to be mostly code in strings sound bleh (formatting, syntax errors, etc), so maaybe add a new directory
tests/doc_examples/(+autofix?) that can both be run as tests, get formatted, etc - and then get sourced straight into the documentation. This does smell like overengineering, but we do have >30 rules...
- I'm somewhat tempted to source these directly from the
- e.g.
- python script that generates
rstfiles will be mostly straightforward.- We already have ways of finding all visitor classes, and iterating over all their error codes.
- Generating the individual rst pages from the methods named above is trivial.
- For generating the table in
rules.rstwe can use the csv-table directive which supports reading the content from a local.csvfile. Dumping the blurbs+error codes+human-readable into a csv is straigthforward. (and including a link to the individual rules pages should be as well)
- The easiest way of hooking in the script is probably to add it to
docs/Makefile. Either as a target that tries to be fancy, or just add it as a commmand to the catch-all target.
thoughts?
augustelalande
Various rules doc improvements:
WIP tasks
yield-in-nursery-or-cancelscopeoryield-in-taskgroup-or-cancelscopeoryield-in-nursery-or-taskgroup-or-cancelscope. (and should it bescope, orcancelscope, orcancelscope-or-timeout, or justtimeout, etc.). Can be fixed with glossary etc when reading docs, but we're also considering people stumbling upon these names innoqastatements or in configs.hoverxrefadditional tasks I have not started on:
I might split out some stuff (e.g. intersphinx) into separate PRs.