From bbc745c698bfafe0835cd753da763674b2411a56 Mon Sep 17 00:00:00 2001
From: FichteFoll <fichtefoll2@googlemail.com>
Date: Thu, 14 Sep 2023 20:19:20 +0200
Subject: [PATCH] [Python] Add syntax support for sphinx-style doc comments

Sphinx (the most common Python documentation tool) uses `#:` comments to
signal documentation comments for its "autodoc" module.

There is no known overlap with other comment punctuation, so this should
be a safe addition.

`TM_COMMENT_START_2` is also added to be able to undo the comment using
`toggle_comment`, but unfortunately it does not work like this
currently because `Default/comment.py` does not prioritize the longest
prefix match of all available comment styles but we don't want this
style to be the default.

https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directive-autoattribute
---
 Python/Comments.tmPreferences      | 11 +++++++++++
 Python/Python.sublime-syntax       | 10 ++++++++++
 Python/tests/syntax_test_python.py |  8 ++++++++
 3 files changed, 29 insertions(+)

diff --git a/Python/Comments.tmPreferences b/Python/Comments.tmPreferences
index 9ca609c7c5..eaafd5da10 100644
--- a/Python/Comments.tmPreferences
+++ b/Python/Comments.tmPreferences
@@ -19,6 +19,17 @@
 				<key>value</key>
 				<string>:</string>
 			</dict>
+			<dict>
+				<!--
+					Cannot be undone using `toggle_comment` at the moment
+					because the earlier `TM_COMMENT_START` is tested first
+					and is a true prefix of this one.
+				-->
+				<key>name</key>
+				<string>TM_COMMENT_START_2</string>
+				<key>value</key>
+				<string>#: </string>
+			</dict>
 		</array>
 	</dict>
 </dict>
diff --git a/Python/Python.sublime-syntax b/Python/Python.sublime-syntax
index ae047a15c5..b3f7668f27 100644
--- a/Python/Python.sublime-syntax
+++ b/Python/Python.sublime-syntax
@@ -364,6 +364,11 @@ contexts:
 ###[ COMMENTS ]###############################################################
 
   comments:
+    # Special Sphinx comment syntax to denote documentation
+    # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directive-autoattribute
+    - match: '#:'
+      scope: punctuation.definition.comment.python
+      push: comment-sphinxdoc-body
     - match: \#
       scope: punctuation.definition.comment.python
       push:
@@ -375,6 +380,11 @@ contexts:
     - match: \n
       pop: 1
 
+  comment-sphinxdoc-body:
+    - meta_scope: comment.line.documentation.python
+    - match: \n
+      pop: 1
+
   shebang:
     - meta_include_prototype: false
     - match: ^\#!
diff --git a/Python/tests/syntax_test_python.py b/Python/tests/syntax_test_python.py
index b3d3ed0472..9348d02a1b 100644
--- a/Python/tests/syntax_test_python.py
+++ b/Python/tests/syntax_test_python.py
@@ -68,6 +68,14 @@
 #^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ comment.block.documentation
 """
 
+#: This is a prefixed "doc comment", supported by sphinx
+# <- comment.line.documentation.python punctuation.definition.comment.python
+#^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ comment.line.documentation.python
+#^ punctuation.definition.comment.python
+attribute = ... #: also supported on the same line
+#               ^^ comment.line.documentation.python punctuation.definition.comment.python
+#                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ comment.line.documentation.python
+
 r'''This is a syntax test file.
 # <- storage.type.string - comment
 #^^^ comment.block.documentation.python punctuation.definition.comment.begin.python