Open hugovk opened 1 week ago
Sphinx regards this as a comment:
Every explicit markup block (starting with
..
) which isn’t a valid markup construct is regarded as a comment:
.. This is a comment
https://devguide.python.org/documentation/markup/#comments
I think we can come up with some rule for a linter to complain about comments that look like directives.
For example, perhaps we could require the first bit of a comment to be UPPERCASE, or require the first bit of a directive to be lowercase.
CPython Docs/
:
$ rg "\.\. [a-z]+: " Doc
Doc/whatsnew/3.8.rst
189:.. TODO: Pablo will sprint on docs at PyCon US 2019.
Doc/whatsnew/3.10.rst
251: ... x: 1,
252: ... y: 2
253: ... z: 3,
280: ... x: 1,
281: ... y: 2,
Doc/whatsnew/2.7.rst
540:.. XXX: Logger objects don't have a class declaration so the link don't work
Doc/tutorial/stdlib.rst
198: ... From: soothsayer@example.org
Doc/using/cmdline.rst
3:.. ATTENTION: You probably should update Misc/python.man, too, if you modify
Doc/library/zoneinfo.rst
220: .. TODO: Add "See `cache_behavior`_" reference when that section is ready.
239: .. TODO: Add "See `cache_behavior`_" reference when that section is ready.
Doc/library/pickle.rst
1200:.. XXX: Add examples showing how to optimize pickles for size (like using
Doc/library/email.generator.rst
101: .. XXX: There should be an option that just does the RFC
114: .. XXX: flatten should take a *policy* keyword.
207: .. XXX: flatten should take a *policy* keyword.
Doc/library/weakref.rst
599: :func:`atexit.register`, ``try: ... finally: ...`` and ``with: ...``
Doc/library/stdtypes.rst
1:.. XXX: reference/datamodel and this have quite a few overlaps!
Doc/extending/embedding.rst
283:.. TODO: threads, code examples do not really behave well if errors happen
And Misc/
contains lots of:
3505:.. date: 2020-02-08-08-01-35
3506:.. nonce: qURKSl
3507:.. section: C API
For example, not detected at https://github.com/python/cpython/pull/121646 and fixed in https://github.com/python/cpython/pull/123783:
Should be: