Skip to content

The IDE you know, rebuilt in Rust. IntelliJ IDEA–style keymap, tool windows and search-everywhere in a fast native app: editor, code insight, debugger, Git, terminal, database and HTTP clients for 60+ languages.

feat(python): highlight docstring tags and keywords by markup format (#2369)

Muu86dc82534ec8
diff --git a/crates/ide-core/src/settings.rs b/crates/ide-core/src/settings.rs
index 64ee8f85f..c0c720509 100644
--- a/crates/ide-core/src/settings.rs
+++ b/crates/ide-core/src/settings.rs
@@ -545,6 +545,9 @@ pub struct EditorSettings {
/// Color Scheme › Language Defaults › Semantic highlighting: local variables and
/// parameters get a colour derived from their name (IDEA's rainbow identifiers).
pub semantic_highlighting: bool,
+ /// Docstring markup format whose tags and keywords the Python editor highlights
+ /// (`plain`, `rest`, `epytext`, `google`, `numpy`).
+ pub docstring_format: String,
/// Color Scheme › Language Defaults › Rainbow brackets: `()`, `[]`, `{}` coloured by depth.
pub rainbow_brackets: bool,
pub ligatures: bool,
@@ -589,6 +592,7 @@ impl Default for EditorSettings {
color_overrides: BTreeMap::new(),
custom_schemes: BTreeMap::new(),
semantic_highlighting: false,
+ docstring_format: "rest".into(),
rainbow_brackets: false,
ligatures: false,
fallback_font: String::new(),
@@ -1303,6 +1307,21 @@ mod tests {
}
}
+ #[test]
+ fn docstring_format_defaults_and_round_trips() {
+ let old: Settings = serde_json::from_str(r#"{"editor":{"semanticHighlighting":true}}"#).unwrap();
+ assert_eq!(old.editor.docstring_format, "rest");
+ assert_eq!(Settings::default().editor.docstring_format, "rest");
+ for format in ["plain", "rest", "epytext", "google", "numpy"] {
+ let mut settings = Settings::default();
+ settings.editor.docstring_format = format.into();
+ let json = serde_json::to_value(&settings).unwrap();
+ assert_eq!(json["editor"]["docstringFormat"], format);
+ let restored: Settings = serde_json::from_value(json).unwrap();
+ assert_eq!(restored.editor.docstring_format, format);
+ }
+ }
+
#[test]
fn tool_window_badges_default_on_and_round_trip() {
let old: Settings = serde_json::from_str(r#"{"appearance":{"showToolWindowNames":true}}"#).unwrap();
diff --git a/docs/plugins/themes.md b/docs/plugins/themes.md
index dcdf17523..dd75c3471 100644
--- a/docs/plugins/themes.md
+++ b/docs/plugins/themes.md
@@ -329,7 +329,7 @@ a token.
<!-- BEGIN GENERATED TOKEN REFERENCE: pnpm gen:theme-docs -->
-252 themeable tokens: 125 in the UI theme file, 127 in the editor colour scheme file.
+255 themeable tokens: 125 in the UI theme file, 130 in the editor colour scheme file.
### Surfaces (UI theme)
@@ -457,6 +457,9 @@ a token.
| `--syn-python-predefined-usage` | `var(--syn-predefined)` | `var(--syn-predefined)` |
| `--syn-python-fstring` | `#a5c261` | `var(--syn-string)` |
| `--syn-python-bytes` | `#a5c261` | `var(--syn-string)` |
+| `--syn-python-docstring-tag` | `var(--syn-doc-comment-tag)` | `var(--syn-doc-comment-tag)` |
+| `--syn-python-docstring-tag-effect` | `var(--syn-doc-comment-tag-effect)` | `var(--syn-doc-comment-tag-effect)` |
+| `--syn-python-docstring-keyword` | `var(--syn-doc-comment-tag-value)` | `var(--syn-doc-comment-tag-value)` |
| `--syn-php-variable` | `var(--syn-property)` | `var(--syn-property)` |
| `--syn-php-function-call` | `var(--syn-function)` | `var(--syn-function)` |
| `--syn-builtin` | `#8888c6` | `#000080` |
diff --git a/plugins/official/harbor-night/themes/harbor-night.scheme.json b/plugins/official/harbor-night/themes/harbor-night.scheme.json
index 75363ac90..bf2df3e5a 100644
--- a/plugins/official/harbor-night/themes/harbor-night.scheme.json
+++ b/plugins/official/harbor-night/themes/harbor-night.scheme.json
@@ -40,6 +40,9 @@
"--syn-python-predefined-usage": "#c4a0f2",
"--syn-python-fstring": "#9ccc7a",
"--syn-python-bytes": "#9ccc7a",
+ "--syn-python-docstring-tag": "#93abc4",
+ "--syn-python-docstring-tag-effect": "none",
+ "--syn-python-docstring-keyword": "#b4c0ce",
"--syn-php-variable": "#b9a3f0",
"--syn-php-function-call": "#f2d07a",
"--syn-builtin": "#6fc3df",
diff --git a/scripts/theme/theme.test.ts b/scripts/theme/theme.test.ts
index d40856e92..afdbecd5a 100644
--- a/scripts/theme/theme.test.ts
+++ b/scripts/theme/theme.test.ts
@@ -80,6 +80,15 @@ describe("theme plugin template", () => {
});
describe("IntelliJ theme import", () => {
+ it("imports Python docstring tags and the OpenIDEA keyword extension", () => {
+ const scheme = convertIcls(`<scheme><attributes>
+ <option name="PY.DOC_COMMENT_TAG"><value><option name="FOREGROUND" value="123456"/></value></option>
+ <option name="OPENIDEA_pyDocstringKeyword"><value><option name="FOREGROUND" value="654321"/></value></option>
+ </attributes></scheme>`);
+ expect(scheme.tokens["--syn-python-docstring-tag"]).toBe("#123456");
+ expect(scheme.tokens["--syn-python-docstring-keyword"]).toBe("#654321");
+ });
+
const themeJson = `{
// comment
"name": "Deep Sea",
diff --git a/src/bindings.ts b/src/bindings.ts
index 0abfad6ef..05c44b505 100644
--- a/src/bindings.ts
+++ b/src/bindings.ts
@@ -3882,6 +3882,11 @@ export type EditorSettings_Deserialize = {
* parameters get a colour derived from their name (IDEA's rainbow identifiers).
*/
semanticHighlighting?: boolean,
+ /**
+ * Docstring markup format whose tags and keywords the Python editor highlights
+ * (`plain`, `rest`, `epytext`, `google`, `numpy`).
+ */
+ docstringFormat?: string,
/** Color Scheme › Language Defaults › Rainbow brackets: `()`, `[]`, `{}` coloured by depth. */
rainbowBrackets?: boolean,
ligatures?: boolean,
@@ -3931,6 +3936,11 @@ export type EditorSettings_Serialize = {
* parameters get a colour derived from their name (IDEA's rainbow identifiers).
*/
semanticHighlighting: boolean,
+ /**
+ * Docstring markup format whose tags and keywords the Python editor highlights
+ * (`plain`, `rest`, `epytext`, `google`, `numpy`).
+ */
+ docstringFormat: string,
/** Color Scheme › Language Defaults › Rainbow brackets: `()`, `[]`, `{}` coloured by depth. */
rainbowBrackets: boolean,
ligatures: boolean,
diff --git a/src/editor/lsp/semantic/index.ts b/src/editor/lsp/semantic/index.ts
index 523612693..643ed4263 100644
--- a/src/editor/lsp/semantic/index.ts
+++ b/src/editor/lsp/semantic/index.ts
@@ -122,7 +122,8 @@ export function semanticRanges(
): SemanticRange[] {
const semantics = languageSemantics(language);
const symbols = semantics?.symbolKinds && tree ? semantics.symbolKinds(tree, doc) : undefined;
- const syntax = semantics?.syntaxRanges && tree ? semantics.syntaxRanges(tree, doc, symbols ?? new Map()) : [];
+ const format = editorPrefs().docstringFormat;
+ const syntax = semantics?.syntaxRanges && tree ? semantics.syntaxRanges(tree, doc, symbols ?? new Map(), format) : [];
const covered = rangeCoverage(syntax);
const serverRanges: Array<{ from: number; to: number }> = [];
const out: SemanticRange[] = [];
@@ -210,6 +211,7 @@ const semanticPlugin = ViewPlugin.fromClass(
private refresh = debounce(() => void this.run(), 600);
private offReady: () => void;
private rainbow = editorPrefs().semanticHighlighting;
+ private docstringFormat = editorPrefs().docstringFormat;
/** Last answer, re-decorated without a request when Semantic highlighting is toggled. */
private last: { doc: Text; tokens: SemanticTokens | null } | null = null;
private destroyed = false;
@@ -232,8 +234,10 @@ const semanticPlugin = ViewPlugin.fromClass(
});
}
const rainbow = editorPrefs().semanticHighlighting;
- if (rainbow === this.rainbow) return;
+ const docstringFormat = editorPrefs().docstringFormat;
+ if (rainbow === this.rainbow && docstringFormat === this.docstringFormat) return;
this.rainbow = rainbow;
+ this.docstringFormat = docstringFormat;
const last = this.last;
// Settings arrive as a compartment reconfiguration; no dispatching inside an update.
if (last && last.doc === u.state.doc)
@@ -246,7 +250,9 @@ const semanticPlugin = ViewPlugin.fromClass(
const tree = syntaxTree(this.view.state);
const semantics = languageSemantics(docOf(this.view)?.language);
const symbols = semantics?.symbolKinds ? semantics.symbolKinds(tree, doc) : undefined;
- const syntax = semantics?.syntaxRanges ? semantics.syntaxRanges(tree, doc, symbols ?? new Map()) : [];
+ const syntax = semantics?.syntaxRanges
+ ? semantics.syntaxRanges(tree, doc, symbols ?? new Map(), editorPrefs().docstringFormat)
+ : [];
const covered = rangeCoverage(syntax);
const retained: Array<{ from: number; to: number }> = [];
const marks = syntax.map((r) => markFor(r.className, r.source).range(r.from, r.to));
diff --git a/src/editor/lsp/semantic/languages.ts b/src/editor/lsp/semantic/languages.ts
index 1808442ca..8d27247e6 100644
--- a/src/editor/lsp/semantic/languages.ts
+++ b/src/editor/lsp/semantic/languages.ts
@@ -36,8 +36,8 @@ export interface ConstructDoc {
export interface LanguageSemantics {
/** Classifies identifiers from the parse tree (`"from:to"` → kind). */
symbolKinds?(tree: Tree, doc: Text): Map<string, string>;
- /** Parse-tree ranges styling what the LSP tokens do not cover. */
- syntaxRanges?(tree: Tree, doc: Text, symbols: Map<string, string>): SemanticRange[];
+ /** Parse-tree ranges styling what the LSP tokens do not cover; `format` is `editor.docstringFormat`. */
+ syntaxRanges?(tree: Tree, doc: Text, symbols: Map<string, string>, format?: string): SemanticRange[];
/** Fast local guesses shown while the server is pending. */
fallbackRanges?(
tree: Tree,
diff --git a/src/editor/lsp/semantic/python/highlight.test.ts b/src/editor/lsp/semantic/python/highlight.test.ts
index f81a61921..b44f4a0d6 100644
--- a/src/editor/lsp/semantic/python/highlight.test.ts
+++ b/src/editor/lsp/semantic/python/highlight.test.ts
@@ -259,3 +259,172 @@ class Box[T]:
expect(classOf("MAX_SIZE")[0]).not.toContain("cm-sem-rainbow-");
});
});
+
+describe("Python docstring markup formats", () => {
+ async function markup(format: string, source: string) {
+ const state = await parse(source);
+ return pythonSyntaxRanges(state.tree, state.doc, undefined, format)
+ .filter((r) => r.className.startsWith("cm-sem-python-docstring-"))
+ .map((r) => [state.doc.sliceString(r.from, r.to), r.className]);
+ }
+
+ it("highlights reStructuredText fields and directives", async () => {
+ const styles = await markup(
+ "rest",
+ `"""Load things.
+
+:param x: name to load
+:returns: loaded value
+.. note:: results are cached
+"""`,
+ );
+ expect(styles).toContainEqual(["param", "cm-sem-python-docstring-tag"]);
+ expect(styles).toContainEqual(["x", "cm-sem-python-docstring-keyword"]);
+ expect(styles).toContainEqual(["returns", "cm-sem-python-docstring-tag"]);
+ expect(styles).toContainEqual(["note::", "cm-sem-python-docstring-tag"]);
+ });
+
+ it("highlights Epytext fields", async () => {
+ const styles = await markup(
+ "epytext",
+ `"""Load things.
+
+@param x: name to load
+@type x: str
+@return: loaded value
+"""`,
+ );
+ expect(styles).toContainEqual(["param", "cm-sem-python-docstring-tag"]);
+ expect(styles).toContainEqual(["x", "cm-sem-python-docstring-keyword"]);
+ expect(styles).toContainEqual(["type", "cm-sem-python-docstring-tag"]);
+ expect(styles).toContainEqual(["return", "cm-sem-python-docstring-tag"]);
+ });
+
+ it("highlights Google sections and entries", async () => {
+ const styles = await markup(
+ "google",
+ `"""Load things.
+
+Args:
+ x (int): first
+ y: second
+
+Returns:
+ Nothing.
+"""`,
+ );
+ expect(styles).toContainEqual(["Args", "cm-sem-python-docstring-tag"]);
+ expect(styles).toContainEqual(["x", "cm-sem-python-docstring-keyword"]);
+ expect(styles).toContainEqual(["y", "cm-sem-python-docstring-keyword"]);
+ expect(styles).toContainEqual(["Returns", "cm-sem-python-docstring-tag"]);
+ });
+
+ it("highlights NumPy sections and entries", async () => {
+ const styles = await markup(
+ "numpy",
+ `"""Load things.
+
+Parameters
+----------
+x : int
+ name to load
+
+Returns
+-------
+str
+ loaded value.
+"""`,
+ );
+ expect(styles).toContainEqual(["Parameters", "cm-sem-python-docstring-tag"]);
+ expect(styles).toContainEqual(["x", "cm-sem-python-docstring-keyword"]);
+ expect(styles).toContainEqual(["Returns", "cm-sem-python-docstring-tag"]);
+ });
+
+ it("leaves docstrings unmarked when the format is plain", async () => {
+ const styles = await markup(
+ "plain",
+ `"""Load things.
+
+:param x: name to load
+"""`,
+ );
+ expect(styles).toEqual([]);
+ });
+
+ it.each(["rest", "epytext"])("highlights %s fields on the opening line in UTF-16 coordinates", async (format) => {
+ const marker = format === "rest" ? ":" : "@";
+ const source = `# 😀\ndef f():\n r"""${marker}param 名称: 😀 description"""\n`;
+ const state = await parse(source);
+ const ranges = pythonSyntaxRanges(state.tree, state.doc, undefined, format);
+ for (const [value, suffix] of [
+ ["param", "tag"],
+ ["名称", "keyword"],
+ ]) {
+ const from = source.indexOf(value!);
+ expect(ranges).toContainEqual({
+ from,
+ to: from + value!.length,
+ className: `cm-sem-python-docstring-${suffix}`,
+ source: "syntax",
+ });
+ }
+ });
+
+ it.each(["b", "br", "rb", "B", "Rb", "f", "fr", "rf"])("never marks %s strings as docstrings", async (prefix) => {
+ expect(await markup("rest", `${prefix}"""Description.\n:param x: value\n"""`)).toEqual([]);
+ });
+
+ it("restricts markup to the first statement of modules, classes and functions", async () => {
+ const source = `# 😀 module\n"""Description.\n:param module: value\n"""
+class C:
+ # comment
+ """Description.
+ :param cls: value
+ """
+ def f(self):
+ """Description.
+ :param func: value
+ """
+ value = """Description.
+ :param assigned: value
+ """
+ """Description.
+ :param later: value
+ """
+if True:
+ """Description.
+ :param conditional: value
+ """
+`;
+ const styles = await markup("rest", source);
+ expect(styles.filter(([, c]) => c?.endsWith("-keyword")).map(([value]) => value)).toEqual([
+ "module",
+ "cls",
+ "func",
+ ]);
+ });
+
+ it("requires indented content after a Google section heading", async () => {
+ expect(await markup("google", '"""Description.\nArgs:\nNot a section.\nNotes:\n"""')).toEqual([]);
+ });
+
+ it.each([
+ ["google", "Args:\n 𐐀名称 (int): value"],
+ ["numpy", "Parameters\n----------\n𐐀名称 : int\n value"],
+ ])("keeps %s keyword ranges in UTF-16 for Unicode names", async (format, content) => {
+ const source = `"""😀 Description.\n${content}\n"""`;
+ const state = await parse(source);
+ const from = source.indexOf("𐐀名称");
+ expect(pythonSyntaxRanges(state.tree, state.doc, undefined, format)).toContainEqual({
+ from,
+ to: from + "𐐀名称".length,
+ className: "cm-sem-python-docstring-keyword",
+ source: "syntax",
+ });
+ });
+
+ it.each(["rest", "epytext", "google", "numpy"])("handles long unfinished %s fields", async (format) => {
+ const source = `"""Description.\n:param ${" ".repeat(2000)}unfinished\nArgs:\nParameters\n----------\nx${" ".repeat(2000)}unfinished\n"""`;
+ expect(await markup(format, source)).not.toContainEqual(["unfinished", "cm-sem-python-docstring-keyword"]);
+ });
+});
diff --git a/src/editor/lsp/semantic/python/highlight.ts b/src/editor/lsp/semantic/python/highlight.ts
index c2269bd35..a7158e43b 100644
--- a/src/editor/lsp/semantic/python/highlight.ts
+++ b/src/editor/lsp/semantic/python/highlight.ts
@@ -472,8 +472,10 @@ export function pythonSyntaxRanges(
tree: Tree,
doc: Text,
symbols: Map<string, PythonSymbolKind> = pythonSymbolKinds(tree, doc),
+ format = "rest",
): SemanticRange[] {
const ranges: SemanticRange[] = [];
+ const firstStatements = new Map<number, number>();
tree.iterate({
enter(cursor) {
const node = cursor.node;
@@ -535,22 +537,30 @@ export function pythonSyntaxRanges(
else if (node.name === "String") {
const statement = node.parent;
const body = statement?.parent;
- let first = body?.firstChild;
- while (first && (first.name === ":" || first.name === "Comment")) first = first.nextSibling;
+ let first = body ? firstStatements.get(body.from) : undefined;
+ if (body && first === undefined) {
+ let child = body.firstChild;
+ while (child && (child.name === ":" || child.name === "Comment")) child = child.nextSibling;
+ first = child?.from ?? -1;
+ firstStatements.set(body.from, first);
+ }
const docstring =
statement?.name === "ExpressionStatement" &&
statement.firstChild?.from === node.from &&
statement.firstChild?.to === node.to &&
- first?.from === statement.from &&
+ first === statement.from &&
(body?.name === "Script" ||
(body?.name === "Body" && ["FunctionDefinition", "ClassDefinition"].includes(body.parent?.name ?? "")));
- if (docstring && !/^[bf]/i.test(text)) style = "python-docstring";
+ if (docstring && !/^[rubf]*[bf][rubf]*['"]/i.test(text)) style = "python-docstring";
else if (/^[rub]*b[rub]*['"]/i.test(text)) style = "python-bytes";
} else if (node.name === "Escape") style = "python-escape";
else if (node.name === "type" && node.parent?.name === "TypeDefinition") style = "keyword";
if (style) className = `cm-sem-${style}`;
if (className) ranges.push({ from: node.from, to: node.to, className, source: "syntax" });
- if (style === "python-docstring") return false;
+ if (style === "python-docstring") {
+ docstringMarkup(node, doc, format, ranges);
+ return false;
+ }
},
});
return ranges;
@@ -562,6 +572,189 @@ const BUILTIN_NAMES = new Set(
),
);
+/** Docstring tag (`:param:`, `Args:`, `@return`) and the name it introduces (`x` in `:param x:`). */
+const DOCSTRING_TAG = "cm-sem-python-docstring-tag";
+const DOCSTRING_KEYWORD = "cm-sem-python-docstring-keyword";
+
+type DocstringPush = (from: number, to: number, className: string) => void;
+
+function scanLines(text: string, base: number, visit: (line: string, at: number) => void) {
+ let pos = 0;
+ for (;;) {
+ const nl = text.indexOf("\n", pos);
+ const end = nl === -1 ? text.length : nl;
+ visit(text.slice(pos, end), base + pos);
+ if (nl === -1) return;
+ pos = nl + 1;
+ }
+}
+
+/** Tagged field line, reST `:param x:` / Epytext `@param x:` (marker `:` or `@`). */
+const REST_FIELD = /^(\s*):([a-zA-Z][\w.]*)(\s+([^:\s][^:]*))?:(\s|$)/;
+const EPYTEXT_FIELD = /^(\s*)@([a-zA-Z][\w.]*)(\s+([^:\s][^:]*))?:(\s|$)/;
+
+function restDocstring(text: string, base: number, push: DocstringPush) {
+ scanLines(text, base, (line, at) => {
+ const directive = /^(\s*\.\.\s+)([\w][\w.-]*)::/.exec(line);
+ if (directive) {
+ const from = at + directive[1]!.length;
+ push(from, from + directive[2]!.length + 2, DOCSTRING_TAG);
+ return;
+ }
+ const field = REST_FIELD.exec(line);
+ if (field) pushField(field, at, push);
+ });
+}
+
+function epytextDocstring(text: string, base: number, push: DocstringPush) {
+ scanLines(text, base, (line, at) => {
+ const field = EPYTEXT_FIELD.exec(line);
+ if (field) pushField(field, at, push);
+ });
+}
+
+/** `:param x:` / `@param x:` — the tag (`param`) and the name it introduces (`x`). */
+function pushField(field: RegExpExecArray, at: number, push: DocstringPush) {
+ const indent = field[1]!.length;
+ const nameFrom = at + indent + 1;
+ push(nameFrom, nameFrom + field[2]!.length, DOCSTRING_TAG);
+ if (field[3]) {
+ const from = nameFrom + field[2]!.length + field[3]!.length - field[3]!.trimStart().length;
+ push(from, from + field[3]!.trim().length, DOCSTRING_KEYWORD);
+ }
+}
+
+const GOOGLE_LISTS = new Set([
+ "args",
+ "arguments",
+ "params",
+ "parameters",
+ "keyword args",
+ "other params",
+ "attributes",
+]);
+const GOOGLE_SECTIONS = new Set([
+ ...GOOGLE_LISTS,
+ "returns",
+ "yields",
+ "receives",
+ "raises",
+ "exceptions",
+ "warns",
+ "warnings",
+ "examples",
+ "example",
+ "notes",
+ "note",
+ "see also",
+]);
+
+function googleDocstring(text: string, base: number, push: DocstringPush) {
+ const lines: Array<{ text: string; at: number }> = [];
+ scanLines(text, base, (line, at) => lines.push({ text: line, at }));
+ let section: { indent: number; entry: number | null } | null = null;
+ for (let i = 0; i < lines.length; i++) {
+ const { text: line, at } = lines[i]!;
+ const header = /^(\s*)([A-Z][\w ]*?):\s*$/.exec(line);
+ let next = i + 1;
+ if (header) while (next < lines.length && !lines[next]!.text.trim()) next++;
+ const following = lines[next]?.text ?? "";
+ if (
+ header &&
+ GOOGLE_SECTIONS.has(header[2]!.trim().toLowerCase()) &&
+ following.length - following.trimStart().length > header[1]!.length
+ ) {
+ push(at + header[1]!.length, at + header[1]!.length + header[2]!.length, DOCSTRING_TAG);
+ section = GOOGLE_LISTS.has(header[2]!.trim().toLowerCase()) ? { indent: header[1]!.length, entry: null } : null;
+ continue;
+ }
+ if (!section) continue;
+ if (!line.trim()) continue;
+ const indent = line.length - line.trimStart().length;
+ if (indent <= section.indent) {
+ section = null;
+ continue;
+ }
+ if (section.entry === null) section.entry = indent;
+ if (indent !== section.entry) continue;
+ const content = line.slice(indent);
+ const colon = content.indexOf(":");
+ if (colon < 1 || (colon + 1 < content.length && !/\s/.test(content[colon + 1]!))) continue;
+ const entry = content.slice(0, colon).trimEnd();
+ const type = entry.indexOf("(");
+ const name = (type < 0 ? entry : entry.slice(0, type)).trimEnd();
+ if (!/^[\p{ID_Continue}*,. [\]]+$/u.test(name)) continue;
+ const from = at + indent;
+ push(from, from + name.length, DOCSTRING_KEYWORD);
+ }
+}
+
+const NUMPY_LISTS = new Set([
+ "parameters",
+ "other parameters",
+ "attributes",
+ "returns",
+ "yields",
+ "receives",
+ "raises",
+ "warns",
+]);
+const NUMPY_SECTIONS = new Set([...NUMPY_LISTS, "notes", "see also", "examples", "warnings"]);
+
+function numpyDocstring(text: string, base: number, push: DocstringPush) {
+ const lines: Array<{ text: string; at: number }> = [];
+ scanLines(text, base, (l, at) => lines.push({ text: l, at }));
+ let section: { indent: number; entry: number | null } | null = null;
+ for (let i = 0; i < lines.length; i++) {
+ const { text: line, at } = lines[i]!;
+ const header = /^(\s*)([A-Z][\w ]*[a-zA-Z])(\s*)$/.exec(line);
+ if (
+ header &&
+ NUMPY_SECTIONS.has(header[2]!.trim().toLowerCase()) &&
+ /^\s*-{3,}\s*$/.test(lines[i + 1]?.text ?? "")
+ ) {
+ push(at + header[1]!.length, at + header[1]!.length + header[2]!.length, DOCSTRING_TAG);
+ section = NUMPY_LISTS.has(header[2]!.trim().toLowerCase()) ? { indent: header[1]!.length, entry: null } : null;
+ i++;
+ continue;
+ }
+ if (!section) continue;
+ if (!line.trim()) continue;
+ const indent = line.length - line.trimStart().length;
+ if (indent < section.indent) {
+ section = null;
+ continue;
+ }
+ if (section.entry === null) section.entry = indent;
+ if (indent !== section.entry) continue;
+ const content = line.slice(indent);
+ const colon = content.indexOf(":");
+ if (colon < 1 || !/\s/.test(content[colon + 1] ?? "")) continue;
+ const name = content.slice(0, colon).trimEnd();
+ if (!/^[\p{ID_Continue}*,. ]+$/u.test(name)) continue;
+ const from = at + indent;
+ push(from, from + name.length, DOCSTRING_KEYWORD);
+ }
+}
+
+/** Marks tags and keywords inside a docstring per the configured markup format. */
+export function docstringMarkup(node: SyntaxNode, doc: Text, format: string, ranges: SemanticRange[]): void {
+ if (format === "plain") return;
+ const literal = doc.sliceString(node.from, node.to);
+ const opening = /^[ru]?("""|'''|"|')/i.exec(literal);
+ if (!opening) return;
+ const base = node.from + opening[0].length;
+ const end = literal.endsWith(opening[1]!) ? literal.length - opening[1]!.length : literal.length;
+ const text = literal.slice(opening[0].length, Math.max(opening[0].length, end));
+ const push: DocstringPush = (from, to, className) => {
+ if (to > from) ranges.push({ from, to, className, source: "syntax" });
+ };
+ if (format === "epytext") epytextDocstring(text, base, push);
+ else if (format === "google") googleDocstring(text, base, push);
+ else if (format === "numpy") numpyDocstring(text, base, push);
+ else restDocstring(text, base, push);
+}
+
/** Fast local guesses while LSP is pending. Server tokens take precedence over these. */
export function pythonFallbackRanges(
tree: Tree,
diff --git a/src/editor/lsp/semantic/python/index.ts b/src/editor/lsp/semantic/python/index.ts
index f7e01453b..fd053e164 100644
--- a/src/editor/lsp/semantic/python/index.ts
+++ b/src/editor/lsp/semantic/python/index.ts
@@ -38,7 +38,8 @@ const SYMBOL_BASES = new Set([
const pythonSemantics: LanguageSemantics = {
symbolKinds: pythonSymbolKinds,
- syntaxRanges: (tree, doc, symbols) => pythonSyntaxRanges(tree, doc, symbols as Map<string, PythonSymbolKind>),
+ syntaxRanges: (tree, doc, symbols, format) =>
+ pythonSyntaxRanges(tree, doc, symbols as Map<string, PythonSymbolKind>, format),
fallbackRanges: (tree, doc, rainbow, symbols) =>
pythonFallbackRanges(tree, doc, rainbow, symbols as Map<string, PythonSymbolKind>),
tokenClasses({ type, modifiers, kind, classes }) {
diff --git a/src/editor/lsp/theme.ts b/src/editor/lsp/theme.ts
index 6ee38d3b2..ff22012ee 100644
--- a/src/editor/lsp/theme.ts
+++ b/src/editor/lsp/theme.ts
@@ -369,6 +369,13 @@ export const lspTheme = EditorView.theme({
".cm-sem-python-predefined-definition": semanticStyle("python-predefined-definition", "predefined"),
".cm-sem-python-predefined-usage": semanticStyle("python-predefined-usage", "predefined"),
".cm-sem-python-docstring, .cm-sem-python-docstring *": semanticStyle("docstring", "string"),
+ // After the docstring wildcard above so the tag's own colour wins inside it.
+ ".cm-sem-python-docstring-tag": {
+ ...semanticStyle("python-docstring-tag", "doc-comment-tag"),
+ textDecoration: "var(--syn-python-docstring-tag-effect, var(--syn-doc-comment-tag-effect, none))",
+ WebkitTextDecoration: "var(--syn-python-docstring-tag-effect, var(--syn-doc-comment-tag-effect, none))",
+ },
+ ".cm-sem-python-docstring-keyword": semanticStyle("python-docstring-keyword", "doc-comment-tag-value"),
".cm-sem-python-bytes": semanticStyle("python-bytes", "string"),
".cm-sem-python-fstring, .cm-sem-python-fstring .tok-string, .cm-sem-python-fstring .tok-string2": semanticStyle(
"python-fstring",
diff --git a/src/features/plugins/intellijTheme.ts b/src/features/plugins/intellijTheme.ts
index 5e19770ee..fbbc2ac7e 100644
--- a/src/features/plugins/intellijTheme.ts
+++ b/src/features/plugins/intellijTheme.ts
@@ -187,6 +187,8 @@ export const ICLS_ATTRIBUTES: Record<string, Array<[Part, string]>> = {
"PY.SELF_PARAMETER": [["FOREGROUND", "--syn-self"]],
"PY.KEYWORD_ARGUMENT": [["FOREGROUND", "--syn-keyword-arg"]],
"PY.DOC_COMMENT": [["FOREGROUND", "--syn-docstring"]],
+ "PY.DOC_COMMENT_TAG": [["FOREGROUND", "--syn-python-docstring-tag"]],
+ OPENIDEA_pyDocstringKeyword: [["FOREGROUND", "--syn-python-docstring-keyword"]],
"PY.BUILTIN_NAME": [["FOREGROUND", "--syn-predefined"]],
MARKDOWN_HEADER_LEVEL_1: [["FOREGROUND", "--syn-markup-heading"]],
MARKDOWN_CODE_SPAN: [["FOREGROUND", "--syn-markup-code"]],
diff --git a/src/features/settings/__tests__/colorScheme.test.tsx b/src/features/settings/__tests__/colorScheme.test.tsx
index 4fd6b211e..749a93343 100644
--- a/src/features/settings/__tests__/colorScheme.test.tsx
+++ b/src/features/settings/__tests__/colorScheme.test.tsx
@@ -122,6 +122,19 @@ describe("scheme actions", () => {
});
describe("doc comment scheme attributes", () => {
+ it("selects Python docstring tags and keywords from their preview", () => {
+ schemePage("editor.colorScheme.python");
+ const preview = screen.getByLabelText("Color scheme preview");
+ const tag = preview.querySelector('code span[style*="--syn-python-docstring-tag"]')!;
+ expect(tag).toHaveTextContent("param");
+ act(() => fireEvent.click(tag));
+ expect(screen.getByRole("treeitem", { name: "Tag", selected: true })).toBeInTheDocument();
+ const keyword = preview.querySelector('code span[style*="--syn-python-docstring-keyword"]')!;
+ expect(keyword).toHaveTextContent("x");
+ act(() => fireEvent.click(keyword));
+ expect(screen.getByRole("treeitem", { name: "Keyword", selected: true })).toBeInTheDocument();
+ });
+
it.each([
["en", "Doc comment", "Tag", "Tag value", "Markup"],
["zh", "文档注释", "标签", "标签值", "标记"],
diff --git a/src/features/settings/languages/PythonInterpreterPage.tsx b/src/features/settings/languages/PythonInterpreterPage.tsx
index ed5fdb4ea..59fbdeacd 100644
--- a/src/features/settings/languages/PythonInterpreterPage.tsx
+++ b/src/features/settings/languages/PythonInterpreterPage.tsx
@@ -7,9 +7,10 @@
import { isCancelled } from "@/platform/ipc";
import { useCallback, useEffect, useMemo, useState, type KeyboardEvent, type MouseEvent } from "react";
import clsx from "clsx";
-import { Button, IconButton, Input, Spinner, showContextMenu, T } from "@/ui";
+import { Button, IconButton, Input, Spinner, showContextMenu, T, type SelectOption } from "@/ui";
import { useProject } from "@/platform/project";
-import { Section, Toggle } from "../components/Form";
+import { DOCSTRING_FORMATS, type DocstringFormat } from "@/platform/editorSettings";
+import { Section, SettingSelect, Toggle } from "../components/Form";
import { effectivePython, listPackages, pip, useSdks, type PythonPackage } from "./api";
import { AddInterpreterDialog } from "./AddInterpreterDialog";
import { useSetting } from "../components/context";
@@ -19,6 +20,18 @@ import { tx } from "@/platform/i18n";
type Op = "install" | "upgrade" | "uninstall";
+const DOCSTRING_LABELS: Record<DocstringFormat, string> = {
+ plain: "Plain",
+ rest: "reStructuredText",
+ epytext: "Epytext",
+ google: "Google",
+ numpy: "NumPy",
+};
+const DOCSTRING_OPTIONS: readonly SelectOption<DocstringFormat>[] = DOCSTRING_FORMATS.map((value) => ({
+ value,
+ label: DOCSTRING_LABELS[value],
+}));
+
interface Job {
op: Op;
target: string;
@@ -317,6 +330,15 @@ export function PythonInterpreterPage() {
/>
</Section>
+ <Section title="Docstrings">
+ <SettingSelect
+ k="editor.docstringFormat"
+ label="Documentation string format"
+ hint="Docstring tags and keywords are highlighted according to this markup format (Color Scheme › Python styles their colours)."
+ options={DOCSTRING_OPTIONS}
+ />
+ </Section>
+
{adding && root && (
<AddInterpreterDialog
root={root}
diff --git a/src/features/settings/pages/editor/colorScheme.tsx b/src/features/settings/pages/editor/colorScheme.tsx
index cd74d36f9..ef74093d9 100644
--- a/src/features/settings/pages/editor/colorScheme.tsx
+++ b/src/features/settings/pages/editor/colorScheme.tsx
@@ -361,7 +361,13 @@ const SAMPLES: Record<string, CodeSample> = {
],
[[' """', "pyDocstring"]],
[[" Syntax Highlighting Demo", "pyDocstring"]],
- [[" @param x Parameter", "pyDocstring"]],
+ [
+ [" :", "pyDocstring"],
+ ["param", "pyDocstringTag"],
+ [" ", "pyDocstring"],
+ ["x", "pyDocstringKeyword"],
+ [": Parameter", "pyDocstring"],
+ ],
[],
[[" Semantic highlighting:", "pyDocstring"]],
[[" Generated spectrum to pick colors for local variables and parameters:", "pyDocstring"]],
diff --git a/src/features/settings/pages/languages.tsx b/src/features/settings/pages/languages.tsx
index e859e63fb..80fe6d832 100644
--- a/src/features/settings/pages/languages.tsx
+++ b/src/features/settings/pages/languages.tsx
@@ -55,6 +55,12 @@ export const LANGUAGE_PAGES: PageSpec[] = [
"install package",
"add interpreter",
"activate virtualenv",
+ "docstrings",
+ "documentation string format",
+ "reStructuredText",
+ "Epytext",
+ "NumPy",
+ "Google",
],
component: PythonInterpreterPage,
},
diff --git a/src/platform/clientSettings.ts b/src/platform/clientSettings.ts
index dd2e4d256..d2dd11baf 100644
--- a/src/platform/clientSettings.ts
+++ b/src/platform/clientSettings.ts
@@ -27,6 +27,7 @@ export const CLIENT_SETTINGS_KEYS = [
"editor.colorOverrides",
"editor.customSchemes",
"editor.semanticHighlighting",
+ "editor.docstringFormat",
"editor.rainbowBrackets",
"editor.softWrap",
"editor.showWhitespace",
diff --git a/src/platform/colorScheme.ts b/src/platform/colorScheme.ts
index a1a48914d..28b679679 100644
--- a/src/platform/colorScheme.ts
+++ b/src/platform/colorScheme.ts
@@ -170,6 +170,8 @@ const BASE_ATTRIBUTES: readonly AttributeDef[] = [
},
syn("pyKeywordArg", "Keyword argument", ["Python"], "keyword-arg"),
syn("pyDocstring", "Docstring", ["Python"], "docstring", { defaultItalic: true }),
+ syn("pyDocstringTag", "Docstring › Tag", ["Python"], "python-docstring-tag"),
+ syn("pyDocstringKeyword", "Docstring › Keyword", ["Python"], "python-docstring-keyword"),
syn("pyBuiltin", "Built-in name", ["Python"], "python-builtin"),
syn("pyDecorator", "Decorator", ["Python"], "annotation"),
syn("pyLocalVariable", "Local variable", ["Python"], "python-local-variable"),
diff --git a/src/platform/editorSettings.ts b/src/platform/editorSettings.ts
index feec9194c..062613a46 100644
--- a/src/platform/editorSettings.ts
+++ b/src/platform/editorSettings.ts
@@ -23,6 +23,10 @@ export interface CustomColorScheme {
export type CustomColorSchemes = Record<string, CustomColorScheme>;
+/** Python docstring markup formats (PyCharm's Python Integrated Tools › Docstring format). */
+export const DOCSTRING_FORMATS = ["plain", "rest", "epytext", "google", "numpy"] as const;
+export type DocstringFormat = (typeof DOCSTRING_FORMATS)[number];
+
export interface LanguageCodeStyle {
/** Java formatter; relative XML paths start at the project root. */
formatter?: "default" | "intellij" | "custom";
@@ -70,6 +74,8 @@ export const EDITOR_EXTRA_DEFAULTS = {
colorOverrides: {} as Record<string, Record<string, TextAttributesOverride>>,
/** Color Scheme › Language Defaults › Semantic highlighting (rainbow locals / parameters). */
semanticHighlighting: false,
+ /** Docstring markup format the Python editor highlights (`plain` disables tag parsing). */
+ docstringFormat: "rest" as DocstringFormat,
/** Color Scheme › Language Defaults › Rainbow brackets. */
rainbowBrackets: false,
ligatures: false,
@@ -252,6 +258,7 @@ export function fontWeightVars(main: unknown, bold: unknown): Record<"--fw-code"
export function validateEditorExtras(raw: unknown): EditorExtras {
const out = coerceLike(raw, EDITOR_EXTRA_DEFAULTS);
if (!["ask", "always", "never"].includes(out.autoImport.importsOnPaste)) out.autoImport.importsOnPaste = "ask";
+ if (!DOCSTRING_FORMATS.includes(out.docstringFormat)) out.docstringFormat = "rest";
out.fontWeight = fontWeightOf(out.fontWeight, EDITOR_EXTRA_DEFAULTS.fontWeight);
out.boldFontWeight = fontWeightOf(out.boldFontWeight, EDITOR_EXTRA_DEFAULTS.boldFontWeight);
return out;
diff --git a/src/platform/icls.test.ts b/src/platform/icls.test.ts
index f5d805e5e..2ec7a566f 100644
--- a/src/platform/icls.test.ts
+++ b/src/platform/icls.test.ts
@@ -20,6 +20,20 @@ const fixture = (name: string) => readFileSync(`src/platform/__fixtures__/colorS
beforeAll(() => _setSchemeSource(readFileSync("src/styles/tokens.css", "utf8")));
describe(".icls schemes", () => {
+ it("round trips Python docstring tags with the Python attribute key and keywords with an extension key", () => {
+ const { scheme } = parseIcls(`<scheme name="Python docs"><attributes>
+ <option name="PY.DOC_COMMENT_TAG"><value><option name="FOREGROUND" value="123456"/></value></option>
+ <option name="OPENIDEA_pyDocstringKeyword"><value><option name="FOREGROUND" value="654321"/></value></option>
+ </attributes></scheme>`);
+ expect(scheme.attributes.pyDocstringTag?.foreground).toBe("#123456");
+ expect(scheme.attributes.pyDocstringKeyword?.foreground).toBe("#654321");
+ const xml = exportIcls("custom-python", { "custom-python": scheme });
+ expect(xml).toContain('name="PY.DOC_COMMENT_TAG"');
+ expect(xml).toContain('name="OPENIDEA_pyDocstringKeyword"');
+ expect(xml).not.toContain("PY_DOC_COMMENT_TAG");
+ expect(parseIcls(xml).scheme.attributes).toMatchObject(scheme.attributes);
+ });
+
it("resolves explicit attribute inheritance independent of XML order and stops cycles", () => {
const { scheme } = parseIcls(`<scheme name="Inherited"><attributes>
<option name="PHP_PARAMETER" baseAttributes="PHP_VAR"/>
diff --git a/src/platform/icls.ts b/src/platform/icls.ts
index ed058df10..9b074818e 100644
--- a/src/platform/icls.ts
+++ b/src/platform/icls.ts
@@ -64,6 +64,8 @@ const ATTRIBUTE_NAMES: Record<string, string> = {
PY_SELF_PARAMETER: "pySelf",
PY_KEYWORD_ARGUMENT: "pyKeywordArg",
PY_DOC_STRING: "pyDocstring",
+ "PY.DOC_COMMENT_TAG": "pyDocstringTag",
+ OPENIDEA_pyDocstringKeyword: "pyDocstringKeyword",
PY_BUILTIN_NAME: "pyBuiltin",
PY_DECORATOR: "pyDecorator",
MARKDOWN_HEADER_LEVEL_1: "mdHeading",
diff --git a/src/platform/locales/text/en.json b/src/platform/locales/text/en.json
index 35e7e1c88..a4fc9cdc6 100644
--- a/src/platform/locales/text/en.json
+++ b/src/platform/locales/text/en.json
@@ -72,6 +72,10 @@
"Comments": "Comments",
"Line comment": "Line comment",
"Doc comment": "Doc comment",
+ "Docstring": "Docstring",
+ "Docstring › Tag": "Docstring › Tag",
+ "Docstring › Keyword": "Docstring › Keyword",
+ "Plain": "Plain",
"Text": "Text",
"Metadata": "Metadata",
"Braces and Operators": "Braces and Operators",
diff --git a/src/platform/locales/text/zh.json b/src/platform/locales/text/zh.json
index 6c568ce7f..cdee202e2 100644
--- a/src/platform/locales/text/zh.json
+++ b/src/platform/locales/text/zh.json
@@ -56,6 +56,9 @@
"Comments": "注释",
"Line comment": "行注释",
"Doc comment": "文档注释",
+ "Docstring": "文档字符串",
+ "Docstring › Tag": "文档字符串 › 标签",
+ "Docstring › Keyword": "文档字符串 › 关键字",
"Metadata": "元数据",
"Braces and Operators": "括号与运算符",
"Markup": "标记",
@@ -65,6 +68,10 @@
"Select Python Environment Folder": "选择 Python 环境文件夹",
"Checking interpreter": "正在检查解释器",
"Cannot run this Python interpreter. Select a working Python executable or virtualenv folder.": "无法运行此 Python 解释器。请选择可用的 Python 可执行文件或虚拟环境文件夹。",
+ "Docstrings": "文档字符串",
+ "Documentation string format": "文档字符串格式",
+ "Docstring tags and keywords are highlighted according to this markup format (Color Scheme › Python styles their colours).": "文档字符串中的标签和关键字会按此标记格式高亮(颜色方案 › Python 定义它们的颜色)。",
+ "Plain": "纯文本",
"The {language} language server can't rename this symbol; renaming only the plugin's indexed names would leave it half renamed": "语言服务器无法重命名此符号({language});仅重命名插件索引的名称会导致重命名不完整",
"Native server declined rename": "语言服务器拒绝重命名",
"document is too large or is not a regular file": "文档过大或不是普通文件",
diff --git a/src/platform/locales/textCatalog.test.ts b/src/platform/locales/textCatalog.test.ts
index 030a9c05b..232d33995 100644
--- a/src/platform/locales/textCatalog.test.ts
+++ b/src/platform/locales/textCatalog.test.ts
@@ -150,10 +150,12 @@ const UNTRANSLATED = new Set<string>([
"Eclipse (macOS)",
"Eclipse Temurin",
"EditorConfig",
+ "Epytext",
"Git",
"GitHub",
"Go",
"Godot",
+ "Google",
"Gradle",
"GraphQL",
"Greenplum",
@@ -169,6 +171,7 @@ const UNTRANSLATED = new Set<string>([
"MySQL",
"Neon",
"Node.js",
+ "NumPy",
"PHP",
"Python",
"npm",
@@ -180,6 +183,7 @@ const UNTRANSLATED = new Set<string>([
"Pyrefly",
"Pyright",
"pytest",
+ "reStructuredText",
"Rust",
"Rustfmt",
"SingleStore",
diff --git a/src/styles/tokens.css b/src/styles/tokens.css
index 5b3604f64..77864c072 100644
--- a/src/styles/tokens.css
+++ b/src/styles/tokens.css
@@ -144,6 +144,9 @@ html {
--syn-python-predefined-usage: var(--syn-predefined);
--syn-python-fstring: #a5c261;
--syn-python-bytes: #a5c261;
+ --syn-python-docstring-tag: var(--syn-doc-comment-tag);
+ --syn-python-docstring-tag-effect: var(--syn-doc-comment-tag-effect);
+ --syn-python-docstring-keyword: var(--syn-doc-comment-tag-value);
/* PhpStorm colours PHP variables and function calls on their own */
--syn-php-variable: var(--syn-property);
--syn-php-function-call: var(--syn-function);
@@ -557,6 +560,9 @@ html {
--syn-python-predefined-usage: var(--syn-predefined);
--syn-python-fstring: var(--syn-string);
--syn-python-bytes: var(--syn-string);
+ --syn-python-docstring-tag: var(--syn-doc-comment-tag);
+ --syn-python-docstring-tag-effect: var(--syn-doc-comment-tag-effect);
+ --syn-python-docstring-keyword: var(--syn-doc-comment-tag-value);
--syn-php-variable: var(--syn-property);
--syn-php-function-call: var(--syn-function);
--syn-builtin: #000080;
@@ -840,6 +846,9 @@ html {
--syn-python-predefined-usage: var(--syn-predefined);
--syn-python-fstring: var(--syn-string);
--syn-python-bytes: var(--syn-string);
+ --syn-python-docstring-tag: var(--syn-doc-comment-tag);
+ --syn-python-docstring-tag-effect: var(--syn-doc-comment-tag-effect);
+ --syn-python-docstring-keyword: var(--syn-doc-comment-tag-value);
--syn-php-variable: var(--syn-property);
--syn-php-function-call: var(--syn-function);
--syn-builtin: #b0b0f0;
@@ -1212,6 +1221,9 @@ html {
--syn-python-predefined-usage: var(--syn-predefined);
--syn-python-fstring: var(--syn-string);
--syn-python-bytes: var(--syn-string);
+ --syn-python-docstring-tag: var(--syn-doc-comment-tag);
+ --syn-python-docstring-tag-effect: var(--syn-doc-comment-tag-effect);
+ --syn-python-docstring-keyword: var(--syn-doc-comment-tag-value);
--syn-php-variable: var(--syn-property);
--syn-php-function-call: var(--syn-function);
--syn-builtin: var(--palette-cyan);