Transition from readme to actually using sphinx docs (#245)

* remove most stuff from README.md, add links to docs in pypi and readme. Add badge for pypi and coverage to readme.

* fix test_messages_documented to look in rules.rst instead of readme

* add claude-translated contributing.rst

* update contributing.rst, replace CONTRIBUTING.md with a link to contributing.rst. Add TOC link to contributing.rst

* transition changelog from markdown to readthedocs

* transition from CHANGELOG.md to docs/changelog.rst

---------

Co-authored-by: Zac Hatfield-Dodds <[email protected]>

Author: jakkdl

Diff for: CHANGELOG.md

@@ -1,182 +1 @@
-# Changelog
-*[CalVer, YY.month.patch](https://calver.org/)*
-
-## 24.5.2
-- ASYNC101 now also warns on anyio & asyncio taskgroup.s
-- Fixed a bug where ASYNC101 and ASYNC91x would not recognize decorators with parameters directly imported. I.e. `@fixture(...)` will now suppress errors.
-
-## 24.5.1
-- Add ASYNC912: no checkpoints in with statement are guaranteed to run.
-- ASYNC100 now properly treats async for comprehensions as checkpoints.
-- ASYNC100 now supports autofixing on asyncio.
-
-## 24.4.2
-- Add ASYNC119: yield in contextmanager in async generator.
-
-## 24.4.1
-- ASYNC91X fix internal error caused by multiple `try/except` incorrectly sharing state.
-
-## 24.3.6
-- ASYNC100 no longer triggers if a context manager contains a `yield`.
-
-## 24.3.5
-- ASYNC102 (no await inside finally or critical except) no longer raises warnings for calls to `aclose()` on objects in trio/anyio code. See https://github.com/python-trio/flake8-async/issues/156
-
-## 24.3.4
-- ASYNC110 (don't loop sleep) now also warns if looping `[trio/anyio].lowlevel.checkpoint()`.
-
-## 24.3.3
-- Add ASYNC251: `time.sleep()` in async method.
-
-## 24.3.2
-- Add ASYNC250: blocking sync call `input()` in async method.
-
-## 24.3.1
-- Removed TRIO117, MultiError removed in trio 0.24.0
-- Renamed the library from flake8-trio to flake8-async, to indicate the checker supports more than just `trio`.
-- Renamed all error codes from TRIOxxx to ASYNCxxx
-- Renamed the binary from flake8-trio to flake8-async
-- Lots of internal renaming.
-- Added asyncio support for several error codes
-- added `--library`
-
-## 23.5.1
-- TRIO91X now supports comprehensions
-- TRIO100 and TRIO91X now supports autofixing
-- Renamed `--enable-visitor-codes-regex` to `--enable`
-- Added `--disable`, `--autofix` and `--error-on-autofix`
-
-## 23.2.5
-- Fix false alarms for `@pytest.fixture`-decorated functions in TRIO101, TRIO910 and TRIO911
-
-## 23.2.4
-- Fix TRIO900 false alarm on nested functions
-- TRIO113 now also works on `anyio.TaskGroup`
-
-## 23.2.3
-- Fix get_matching_call when passed a single string as base. Resolves possibly several false alarms, TRIO210 among them.
-
-## 23.2.2
-- Rename TRIO107 to TRIO910, and TRIO108 to TRIO911, and making them optional by default.
-- Allow `@pytest.fixture()`-decorated async generators, since they're morally context managers
-- Add support for checking code written against [`anyio`](https://anyio.readthedocs.io/en/stable/)
-- Add TRIO118: Don't assign the value of `anyio.get_cancelled_exc_class()` to a variable, since that breaks linter checks and multi-backend programs.
-
-## 23.2.1
-- TRIO103 and TRIO104 no longer triggers when `trio.Cancelled` has been handled in previous except handlers.
-- Add TRIO117: Reference to deprecated `trio.[NonBase]MultiError`; use `[Base]ExceptionGroup` instead.
-- Add TRIO232: blocking sync call on file object.
-- Add TRIO212: blocking sync call on `httpx.Client` object.
-- Add TRIO222: blocking sync call to `os.wait*`
-- TRIO221 now also looks for `os.posix_spawn[p]`
-
-## 23.1.4
-- TRIO114 avoids a false alarm on posonly args named "task_status"
-- TRIO116 will now match on any attribute parameter named `.inf`, not just `math.inf`.
-- TRIO900 now only checks `@asynccontextmanager`, not other decorators passed with --no-checkpoint-warning-decorators.
-
-## 23.1.3
-- Add TRIO240: usage of `os.path` in async function.
-- Add TRIO900: ban async generators not decorated with known safe decorator
-
-## 23.1.2
-- Add TRIO230, TRIO231 - sync IO calls in async function
-
-## 23.1.1
-- Add TRIO210, TRIO211 - blocking sync call in async function, using network packages (requests, httpx, urllib3)
-- Add TRIO220, TRIO221 - blocking sync call in async function, using subprocess or os.
-
-## 22.12.5
-- The `--startable-in-context-manager` and `--trio200-blocking-calls` options now handle spaces and newlines.
-- Now compatible with  [flake8-noqa](https://pypi.org/project/flake8-noqa/)'s NQA102 and NQA103 checks.
-
-## 22.12.4
-- TRIO200 no longer warns on directly awaited calls
-
-## 22.12.3
-- Worked around configuration-parsing bug for TRIO200 warning (more to come)
-
-## 22.12.2
-- Add TRIO200: User-configured blocking sync call  in async function
-
-## 22.12.1
-- TRIO114 will now trigger on the unqualified name, will now only check the first parameter
-  directly, and parameters to function calls inside that.
-- TRIO113 now only supports names that are valid identifiers, rather than fnmatch patterns.
-- Add TRIO115: Use `trio.lowlevel.checkpoint()` instead of `trio.sleep(0)`.
-
-## 22.11.5
-- Add TRIO116: `trio.sleep()` with >24 hour interval should usually be `trio.sleep_forever()`.
-
-## 22.11.4
-- Add TRIO114 Startable function not in `--startable-in-context-manager` parameter list.
-
-## 22.11.3
-- Add TRIO113, prefer `await nursery.start(...)` to `nursery.start_soon()` for compatible functions when opening a context manager
-
-## 22.11.2
-- TRIO105 now also checks that you `await`ed `nursery.start()`.
-
-## 22.11.1
-- TRIO102 is no longer skipped in (async) context managers, since it's not a missing-checkpoint warning.
-
-## 22.9.2
-- Fix a crash on nontrivial decorator expressions (calls, PEP-614) and document behavior.
-
-## 22.9.1
-- Add `--no-checkpoint-warning-decorators` option, to disable missing-checkpoint warnings for certain decorated functions.
-
-## 22.8.8
-- Fix false alarm on TRIO107 with checkpointing `try` and empty `finally`
-- Fix false alarm on TRIO107&108 with infinite loops
-
-## 22.8.7
-- TRIO107+108 now ignores `asynccontextmanager`s, since both `__aenter__` and `__aexit__` should checkpoint. `async with` is also treated as checkpointing on both enter and exit.
-- TRIO107 now completely ignores any function whose body consists solely of ellipsis, pass, or string constants.
-- TRIO103, 107 and 108 now inspects `while` conditions and `for` iterables to avoid false alarms on a couple cases where the loop body is guaranteed to run at least once.
-
-## 22.8.6
-- TRIO103 now correctly handles raises in loops, i.e. `raise` in else is guaranteed to run unless there's a `break` in the body.
-
-## 22.8.5
-- Add TRIO111: Variable, from context manager opened inside nursery, passed to `start[_soon]` might be invalidly accessed while in use, due to context manager closing before the nursery. This is usually a bug, and nurseries should generally be the inner-most context manager.
-- Add TRIO112: this single-task nursery could be replaced by awaiting the function call directly.
-
-## 22.8.4
-- Fix TRIO108 raising errors on yields in some sync code.
-- TRIO109 now skips all decorated functions to avoid false alarms
-
-## 22.8.3
-- TRIO108 now gives multiple error messages; one for each path lacking a guaranteed checkpoint
-
-## 22.8.2
-- Merged TRIO108 into TRIO107
-- TRIO108 now handles checkpointing in async iterators
-
-## 22.8.1
-- Added TRIO109: Async definitions should not have a `timeout` parameter. Use `trio.[fail/move_on]_[at/after]`
-- Added TRIO110: `while <condition>: await trio.sleep()` should be replaced by a `trio.Event`.
-
-## 22.7.6
-- Extend TRIO102 to also check inside `except BaseException` and `except trio.Cancelled`
-- Extend TRIO104 to also check for `yield`
-- Update error messages on TRIO102 and TRIO103
-
-## 22.7.5
-- Add TRIO103: `except BaseException` or `except trio.Cancelled` with a code path that doesn't re-raise
-- Add TRIO104: "Cancelled and BaseException must be re-raised" if user tries to return or raise a different exception.
-- Added TRIO107: Async functions must have at least one checkpoint on every code path, unless an exception is raised
-- Added TRIO108: Early return from async function must have at least one checkpoint on every code path before it.
-
-## 22.7.4
-- Added TRIO105 check for not immediately `await`ing async trio functions.
-- Added TRIO106 check that trio is imported in a form that the plugin can easily parse.
-
-## 22.7.3
-- Added TRIO102 check for unsafe checkpoints inside `finally:` blocks
-
-## 22.7.2
-- Avoid `TRIO100` false-alarms on cancel scopes containing `async for` or `async with`.
-
-## 22.7.1
-- Initial release with TRIO100 and TRIO101
+The flake8-async changelog can now be seen at https://flake8-async.readthedocs.io/en/latest/changelog.html

Diff for: CONTRIBUTING.md

@@ -1,82 +1 @@
-# Contributor Guide
-
-Contributions welcome!  We'll expand this guide as we go.
-
-
-## Development
-
-When you wish to add a check to `flake8-async` please ensure the following:
-
-- `README.md` gets a one line about your new warning
-- Add a CHANGELOG entry (see 'Releasing a new version' below)
-- A test in `tests/eval_files` is added for your check. See the "Test generator" heading below.
-To run our test suite please use tox.
-
-```console
-# Formatting and Linting
-pre-commit run [--all-files]
-# Run tests against current version of python and latest flake8
-tox -e testenv
-# Run all test environments (tox -a for a complete list)
-tox
-# Tip: Use --parallel and --develop, to save time when modifying and rerunning.
-tox -p --develop
-# --quiet and --parallel-no-spinner are also nice for output control.
-```
-
-## Meta-tests
-To check that all codes are tested and documented there's a test that error codes mentioned in `README.md`, `CHANGELOG.md` (matching `TRIO\d\d\d`), the keys in `flake8_async.Error_codes` and codes parsed from filenames and files in `tests/eval_files/`, are all equal.
-
-## Test generator
-Tests are automatically generated for files in the `tests/eval_files/` directory, with the code that it's testing interpreted from the file name. The file extension is split off, if there's a match for for `_py\d*` it strips that off and uses it to determine if there's a minimum python version for which the test should only run.
-
-### `# AUTOFIX`
-Files in `tests/eval_files` with this marker will have two files in `tests/autofix_files/`. One with the same name containing the code after being autofixed, and a diff file between those two.  
-During tests the result of running the checker on the eval file with autofix enabled will be compared to the content of the autofix file and will print a diff (if `-s` is on) and assert that the content is the same. `--generate-autofix` is added as a pytest flag to ease development, which will print a diff (with `-s`) and overwrite the content of the autofix file.  
-Files without this marker will be checked that they *don't* modify the file content.
-
-### `error:`
-Lines containing `error:` are parsed as expecting an error of the code matching the file name, with everything on the line after the colon `eval`'d and passed as arguments to `flake8_async.Error_codes[<error_code>].str_format`. The `globals` argument to `eval` contains a `lineno` variable assigned the current line number, and the `flake8_async.Statement` namedtuple. The first element after `error:` *must* be an integer containing the column where the error on that line originates.
-#### `TRIOxxx:`
-You can instead of `error` specify the error code.
-
-### `# ARG`
-With `# ARG` lines you can also specify command-line arguments that should be passed to the plugin when parsing a file. Can be specified multiple times for several different arguments.  
-Generated tests will by default `--select` the error code of the file, which will enable any visitors that can generate that code (and if those visitors can raise other codes they might be raised too). This can be overridden by adding an `# ARG --select=...` line.
-
-### Library parametrization
-Eval files are evaluated with each supported library. It does this by replacing all instances of the `BASE_LIBRARY` ("trio" by default) with the two other libraries, and setting the corresponding flag (`--anyio` or `--asyncio`).
-### `# BASE_LIBRARY anyio` / `# BASE_LIBRARY asyncio`
-Defaults to `trio`. Used to specify the primary library an eval file is testing.
-
-#### `# ANYIO_NO_ERROR`, `# TRIO_NO_ERROR`, `# ASYNCIO_NO_ERROR`
-A file which is marked with this will ignore all `# error` or `# TRIO...` comments when running with anyio. Use when an error is library-specific and replacing all instances means the file should no longer raise any errors.
-### `# NOANYIO`, `# NOTRIO`, `#NOASYNCIO`
-Disables checking a file with the specified library. Should be used somewhat sparingly, and always have a comment motivating its use.
-
-## Running pytest outside tox
-If you don't want to bother with tox to quickly test stuff, you'll need to install the following dependencies:
-```
-pip install -e .
-pip install pytest pytest-cov hypothesis hypothesmith flake8
-```
-
-## Style Guide
-
-**Code style:** code review should focus on correctness, performance, and readability.
-Low-level nitpicks are handled *exclusively* by our formatters and linters, so if
-`tox` passes there's nothing else to say.
-
-**Terminology:** use "false/missed alarm" rather than "true/false positive", or the
-even worse "type I/II error".  "False alarm" or "missed alarm" have obvious meanings
-which do not rely on confusing conventions (is noticing an error positive or negative?)
-or rote memorization of an arbitrary convention.
-
-
-## Releasing a new version
-We want to ship bigfixes or new features as soon as they're ready,
-so our release process is automated:
-
-1. Increment `__version__` in `src/flake8_async.py`
-2. Ensure there's a corresponding entry in `CHANGELOG.md` with same version
-3. Merge to master, and CI will do the rest!
+The flake8-async contributor guide can be seen at https://flake8-async.readthedocs.io/en/latest/contributing.html