Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Directive with single colon instead of double #118

Open
hugovk opened this issue Sep 12, 2024 · 1 comment
Open

Directive with single colon instead of double #118

hugovk opened this issue Sep 12, 2024 · 1 comment
Labels
enhancement New feature or request

Comments

@hugovk
Copy link
Collaborator

hugovk commented Sep 12, 2024

For example, not detected at python/cpython#121646 and fixed in python/cpython#123783:

   .. versionadded: 3.14

Should be:

   .. versionadded:: 3.14
@hugovk hugovk added the enhancement New feature or request label Sep 12, 2024
@hugovk
Copy link
Collaborator Author

hugovk commented Sep 12, 2024

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: [email protected]

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

1 participant