Skip to content

Conversation

JaeHyuckSa
Copy link
Contributor

Trac ticket number

ticket-36570

Checklist

  • This PR targets the main branch.
  • The commit message is written in past tense, mentions the ticket number, and ends with a period.
  • I have checked the "Has patch" ticket flag in the Trac system.
  • I have added or updated relevant tests.
  • I have added or updated relevant docs, including release notes if applicable.
  • I have attached screenshots in both light and dark modes for any UI changes.

@sarahboyce
Copy link
Contributor

sarahboyce commented Aug 25, 2025

There are quite a few more, e.g. :py:mod:, :py:attr:, :py:ref:, :py:meth:, that can also be updated 👍
Please rebase on main and resolve the conflicts also ⭐

@JaeHyuckSa
Copy link
Contributor Author

There are quite a few more, e.g. :py:mod:, :py:attr:, :py:ref:, :py:meth:, that can also be updated 👍 Please rebase on main and resolve the conflicts also ⭐

@sarahboyce Thank you! I’ve updated all the values you pointed out.

It would be even more helpful if there were a hook to catch any :py: parts early on. Do you think it might be possible to catch these through something like a pre-commit hook or during CI?

@JaeHyuckSa JaeHyuckSa force-pushed the issue-36570 branch 2 times, most recently from fabd252 to 3ef5154 Compare August 25, 2025 15:51
@smithdc1
Copy link
Member

Do you think it might be possible to catch these through something like a pre-commit hook or during CI?

How about something like this?

diff --git a/docs/lint.py b/docs/lint.py
index cb129997b2..5c8c8af749 100644
--- a/docs/lint.py
+++ b/docs/lint.py
@@ -5,12 +5,14 @@ from os.path import abspath, dirname, splitext
 from unittest import mock
 
 from sphinxlint.checkers import (
+    _ROLE_BODY,
     _is_long_interpreted_text,
     _is_very_long_string_literal,
     _starts_with_anonymous_hyperlink,
     _starts_with_directive_or_hyperlink,
 )
 from sphinxlint.checkers import checker as sphinxlint_checker
+from sphinxlint.rst import SIMPLENAME
 from sphinxlint.sphinxlint import check_text
 from sphinxlint.utils import PER_FILE_CACHES, hide_non_rst_blocks
 
@@ -116,6 +118,24 @@ def check_line_too_long_django(file, lines, options=None):
             yield lno + 1, f"Line too long ({len(line) - 1}/{options.max_line_length})"
 
 
+_PYTHON_DOMAIN = re.compile(f":py:{SIMPLENAME}:`{_ROLE_BODY}`")
+
+
+@sphinxlint_checker(".rst", enabled=False, rst_only=True)
+def check_python_domain_in_roles(file, lines, options=None):
+    """
+    :py: indicates the Python language domain. This means code writen in
+    Python, not Python built-ins in particular.
+
+    Bad:    :py:class:`email.message.EmailMessage`
+    Good:   :class:`email.message.EmailMessage`
+    """
+    for lno, line in enumerate(lines, start=1):
+        role = _PYTHON_DOMAIN.search(line)
+        if role:
+            yield lno, f":py domain is the default and can be omitted {role.group(0)!r}"
+
+
 import sphinxlint  # noqa: E402
 
 sphinxlint.check_file = django_check_file

@JaeHyuckSa
Copy link
Contributor Author

JaeHyuckSa commented Aug 26, 2025

Do you think it might be possible to catch these through something like a pre-commit hook or during CI?

How about something like this?

Hi @smithdc1 — thank you very much. This looks great to me. Would it be okay if I open a PR for this?

@smithdc1
Copy link
Member

Sure, no problem. I'd suggest adding it as a second commit to this PR though, rather than opening it separately.

@JaeHyuckSa
Copy link
Contributor Author

JaeHyuckSa commented Aug 26, 2025

@smithdc1 Thank you. I’ve applied your suggestions, and it seems to be working well. 👍
It also shows up correctly in Actions! ☺️

Copy link
Contributor

@sarahboyce sarahboyce left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you both!

@sarahboyce sarahboyce merged commit 05bac8c into django:main Aug 28, 2025
24 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants