From bc77ddb90ce7fd29c6100dbf352c9b3c8ed287f0 Mon Sep 17 00:00:00 2001 From: Matthew Woehlke Date: Tue, 14 Mar 2023 15:03:48 -0400 Subject: Utilities/Sphinx: Factor out part of CMakeXRefRole Refactor the portion of CMakeXRefRole that escapes angle brackets in reference titles to the equivalent of a C++ template class. This will allow us to reuse that logic for reference roles that aren't derived from XRefRole. --- Utilities/Sphinx/cmake.py | 42 +++++++++++++++++++++++++++++------------- 1 file changed, 29 insertions(+), 13 deletions(-) diff --git a/Utilities/Sphinx/cmake.py b/Utilities/Sphinx/cmake.py index ba1fa4a..111ea04 100644 --- a/Utilities/Sphinx/cmake.py +++ b/Utilities/Sphinx/cmake.py @@ -5,7 +5,7 @@ import os import re from dataclasses import dataclass -from typing import Any, List, cast +from typing import Any, List, Tuple, cast # Override much of pygments' CMakeLexer. # We need to parse CMake syntax definitions, not CMake code. @@ -66,6 +66,7 @@ CMakeLexer.tokens["root"] = [ from docutils.utils.code_analyzer import Lexer, LexerError from docutils.parsers.rst import Directive, directives from docutils.transforms import Transform +from docutils.nodes import Element, Node, TextElement, system_message from docutils import io, nodes from sphinx.directives import ObjectDescription, nl_escape_re @@ -482,15 +483,38 @@ class CMakeSignatureObject(CMakeObject): return super().run() -class CMakeXRefRole(XRefRole): - +class CMakeReferenceRole: # See sphinx.util.nodes.explicit_title_re; \x00 escapes '<'. _re = re.compile(r'^(.+?)(\s*)(?$', re.DOTALL) + + @staticmethod + def _escape_angle_brackets(text: str) -> str: + # CMake cross-reference targets frequently contain '<' so escape + # any explicit `` with '<' not preceded by whitespace. + while True: + m = CMakeReferenceRole._re.match(text) + if m and len(m.group(2)) == 0: + text = f'{m.group(1)}\x00<{m.group(3)}>' + else: + break + return text + + def __class_getitem__(cls, parent: Any): + class Class(parent): + def __call__(self, name: str, rawtext: str, text: str, + *args, **kwargs + ) -> Tuple[List[Node], List[system_message]]: + text = CMakeReferenceRole._escape_angle_brackets(text) + return super().__call__(name, rawtext, text, *args, **kwargs) + return Class + +class CMakeXRefRole(CMakeReferenceRole[XRefRole]): + _re_sub = re.compile(r'^([^()\s]+)\s*\(([^()]*)\)$', re.DOTALL) _re_genex = re.compile(r'^\$<([^<>:]+)(:[^<>]+)?>$', re.DOTALL) _re_guide = re.compile(r'^([^<>/]+)/([^<>]*)$', re.DOTALL) - def __call__(self, typ, rawtext, text, *args, **keys): + def __call__(self, typ, rawtext, text, *args, **kwargs): if typ == 'cmake:command': # Translate a CMake command cross-reference of the form: # `command_name(SUB_COMMAND)` @@ -508,15 +532,7 @@ class CMakeXRefRole(XRefRole): m = CMakeXRefRole._re_guide.match(text) if m: text = '%s <%s>' % (m.group(2), text) - # CMake cross-reference targets frequently contain '<' so escape - # any explicit `` with '<' not preceded by whitespace. - while True: - m = CMakeXRefRole._re.match(text) - if m and len(m.group(2)) == 0: - text = '%s\x00<%s>' % (m.group(1), m.group(3)) - else: - break - return XRefRole.__call__(self, typ, rawtext, text, *args, **keys) + return super().__call__(typ, rawtext, text, *args, **kwargs) # We cannot insert index nodes using the result_nodes method # because CMakeXRefRole is processed before substitution_reference -- cgit v0.12 From 302f5171d8bc9877fc1e9b34024d5c0322f53a69 Mon Sep 17 00:00:00 2001 From: Matthew Woehlke Date: Tue, 14 Mar 2023 15:20:47 -0400 Subject: Utilities/Sphinx: Add 'cref' role Add a role that can be used to create local links (a la '`LINK`_'), but that also applies literal style. This is particularly useful for referring to subcommands within the command's documentation in a style that is consistent with ':command:`BAR `' but is much less verbose. Although this is intended for subcommands, it works with any local reference. Co-authored-by: Brad King --- Help/dev/documentation.rst | 4 ++++ Source/cmRST.cxx | 1 + Tests/CMakeLib/testRST.expect | 7 ++++++- Tests/CMakeLib/testRST.rst | 7 ++++++- Utilities/Sphinx/cmake.py | 19 ++++++++++++++++++- 5 files changed, 35 insertions(+), 3 deletions(-) diff --git a/Help/dev/documentation.rst b/Help/dev/documentation.rst index b7a77c9..c6fb7a6 100644 --- a/Help/dev/documentation.rst +++ b/Help/dev/documentation.rst @@ -395,6 +395,10 @@ object names like ``OUTPUT_NAME_``. The form ``a ``, with a space preceding ``<``, is still interpreted as a link text with an explicit target. +Additionally, the ``cref`` role may be used to create references +to local targets that have literal styling. This is especially +useful for referencing a subcommand in the command's documentation. + .. _`list()`: https://cmake.org/cmake/help/latest/command/list.html .. _`list(APPEND)`: https://cmake.org/cmake/help/latest/command/list.html .. _`list(APPEND) sub-command`: https://cmake.org/cmake/help/latest/command/list.html diff --git a/Source/cmRST.cxx b/Source/cmRST.cxx index 5ff7009..f48330d 100644 --- a/Source/cmRST.cxx +++ b/Source/cmRST.cxx @@ -33,6 +33,7 @@ cmRST::cmRST(std::ostream& os, std::string docroot) , VersionDirective("^.. version(added|changed)::[ \t]*(.*)$") , ModuleRST(R"(^#\[(=*)\[\.rst:$)") , CMakeRole("(:cmake)?:(" + "cref|" "command|cpack_gen|generator|genex|" "variable|envvar|module|policy|" "prop_cache|prop_dir|prop_gbl|prop_inst|prop_sf|" diff --git a/Tests/CMakeLib/testRST.expect b/Tests/CMakeLib/testRST.expect index 483e220..424b7d4 100644 --- a/Tests/CMakeLib/testRST.expect +++ b/Tests/CMakeLib/testRST.expect @@ -26,10 +26,15 @@ Generator expression ``$`` with brackets and parameter. Generator expression ``some genex`` with space and target. Generator expression ``$`` with brackets, space, and target. Generator expression ``$`` with brackets, parameter, space, and target. -Inline literal ``~!@#$%^&*( )_+-=\\[]{}'":;,<>.?/``. +Inline cref ``Link Dest``. +Inline cref ``Link_Dest_``. +Inline cref ``Link Text``. +Inline cref ``Link_Text_``. +Inline link Link Dest. Inline link Link Text. Inline link Link Text . Inline literal ``__`` followed by inline link Link Text. +Inline literal ``~!@#$%^&*( )_+-=\\[]{}'":;,<>.?/``. First TOC entry. diff --git a/Tests/CMakeLib/testRST.rst b/Tests/CMakeLib/testRST.rst index c23b69a..3a38407 100644 --- a/Tests/CMakeLib/testRST.rst +++ b/Tests/CMakeLib/testRST.rst @@ -33,10 +33,15 @@ Generator expression :genex:`$` with brackets and parameter. Generator expression :genex:`some genex ` with space and target. Generator expression :genex:`$ ` with brackets, space, and target. Generator expression :genex:`$ ` with brackets, parameter, space, and target. -Inline literal ``~!@#$%^&*( )_+-=\\[]{}'":;,<>.?/``. +Inline cref :cref:`Link Dest`. +Inline cref :cref:`Link_Dest_`. +Inline cref :cref:`Link Text `. +Inline cref :cref:`Link_Text_ `. +Inline link `Link Dest`_. Inline link `Link Text `_. Inline link `Link Text \ `_. Inline literal ``__`` followed by inline link `Link Text `_. +Inline literal ``~!@#$%^&*( )_+-=\\[]{}'":;,<>.?/``. .. |not replaced| replace:: not replaced through toctree .. |not replaced in literal| replace:: replaced in parsed literal diff --git a/Utilities/Sphinx/cmake.py b/Utilities/Sphinx/cmake.py index 111ea04..5990f8a 100644 --- a/Utilities/Sphinx/cmake.py +++ b/Utilities/Sphinx/cmake.py @@ -5,7 +5,7 @@ import os import re from dataclasses import dataclass -from typing import Any, List, Tuple, cast +from typing import Any, List, Tuple, Type, cast # Override much of pygments' CMakeLexer. # We need to parse CMake syntax definitions, not CMake code. @@ -72,6 +72,7 @@ from docutils import io, nodes from sphinx.directives import ObjectDescription, nl_escape_re from sphinx.domains import Domain, ObjType from sphinx.roles import XRefRole +from sphinx.util.docutils import ReferenceRole from sphinx.util.nodes import make_refnode from sphinx.util import logging, ws_re from sphinx import addnodes @@ -508,6 +509,21 @@ class CMakeReferenceRole: return super().__call__(name, rawtext, text, *args, **kwargs) return Class +class CMakeCRefRole(CMakeReferenceRole[ReferenceRole]): + nodeclass: Type[Element] = nodes.reference + innernodeclass: Type[TextElement] = nodes.literal + classes: List[str] = ['cmake', 'literal'] + + def run(self) -> Tuple[List[Node], List[system_message]]: + refnode = self.nodeclass(self.rawtext) + self.set_source_info(refnode) + + refnode['refid'] = nodes.make_id(self.target) + refnode += self.innernodeclass(self.rawtext, self.title, + classes=self.classes) + + return [refnode], [] + class CMakeXRefRole(CMakeReferenceRole[XRefRole]): _re_sub = re.compile(r'^([^()\s]+)\s*\(([^()]*)\)$', re.DOTALL) @@ -617,6 +633,7 @@ class CMakeDomain(Domain): # Other `object_types` cannot be created except by the `CMakeTransform` } roles = { + 'cref': CMakeCRefRole(), 'command': CMakeXRefRole(fix_parens = True, lowercase = True), 'cpack_gen': CMakeXRefRole(), 'envvar': CMakeXRefRole(), -- cgit v0.12