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.
TypeScript code-editorcross-platformdapdatabase-clientdebuggerdesktop-appdeveloper-toolsgithttp-clientideintellijlsprusttauriterminal
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.rsindex 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.mdindex 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.jsonindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsxindex 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.tsxindex 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 && (<AddInterpreterDialogroot={root}diff --git a/src/features/settings/pages/editor/colorScheme.tsx b/src/features/settings/pages/editor/colorScheme.tsxindex 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.tsxindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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__/colorSbeforeAll(() => _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.tsindex 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.jsonindex 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.jsonindex 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.tsindex 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.cssindex 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);