sphinx-contrib / sphinx-lint

Check for stylistic and formal issues in .rst and .py files included in the documentation
https://pypi.org/project/sphinx-lint/
Other
70 stars 20 forks source link

Directive with single colon instead of double #118

Open hugovk opened 1 week ago

hugovk commented 1 week ago

For example, not detected at https://github.com/python/cpython/pull/121646 and fixed in https://github.com/python/cpython/pull/123783:

   .. versionadded: 3.14

Should be:

   .. versionadded:: 3.14
hugovk commented 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