diff --git a/CHANGES b/CHANGES index 2743788ac..fe87bf9b9 100644 --- a/CHANGES +++ b/CHANGES @@ -7,6 +7,9 @@ Dependencies Incompatible changes -------------------- +* #9023: Change the CSS classes on :rst:role:`cpp:expr` and + :rst:role:`cpp:texpr`. + Deprecated ---------- diff --git a/doc/extdev/nodes.rst b/doc/extdev/nodes.rst index d327e1cb0..77872df40 100644 --- a/doc/extdev/nodes.rst +++ b/doc/extdev/nodes.rst @@ -17,6 +17,7 @@ These nodes form the top-most levels of object descriptions. .. autoclass:: desc_signature .. autoclass:: desc_signature_line .. autoclass:: desc_content +.. autoclass:: desc_inline Nodes for high-level structure in signatures ............................................ diff --git a/sphinx/addnodes.py b/sphinx/addnodes.py index 17f579c0e..2d117d7a9 100644 --- a/sphinx/addnodes.py +++ b/sphinx/addnodes.py @@ -151,13 +151,16 @@ class desc(nodes.Admonition, nodes.Element): # that forces the specification of the domain and objtyp? -class desc_signature(nodes.Part, nodes.Inline, nodes.TextElement): +class desc_signature(_desc_classes_injector, nodes.Part, nodes.Inline, nodes.TextElement): """Node for a single object signature. As default the signature is a single-line signature. Set ``is_multiline = True`` to describe a multi-line signature. In that case all child nodes must be :py:class:`desc_signature_line` nodes. + + This node always has the classes ``sig`` and ``sig-object``. """ + classes = ['sig', 'sig-object'] @property def child_text_separator(self): @@ -183,6 +186,22 @@ class desc_content(nodes.General, nodes.Element): Must be the last child node in a :py:class:`desc` node. """ + +class desc_inline(_desc_classes_injector, nodes.Inline, nodes.TextElement): + """Node for a signature fragment in inline text. + + This is for example used for roles like :rst:role:`cpp:expr`. + + This node always has the classes ``sig``, ``sig-inline``, + and the name of the domain it belongs to. + """ + classes = ['sig', 'sig-inline'] + + def __init__(self, domain: str, *args, **kwargs): + super().__init__(*args, **kwargs) + self['classes'].append(domain) + + # Nodes for high-level structure in signatures ############################################## @@ -507,20 +526,25 @@ class manpage(nodes.Inline, nodes.FixedTextElement): def setup(app: "Sphinx") -> Dict[str, Any]: app.add_node(toctree) + app.add_node(desc) app.add_node(desc_signature) app.add_node(desc_signature_line) + app.add_node(desc_content) + app.add_node(desc_inline) + + app.add_node(desc_name) app.add_node(desc_addname) app.add_node(desc_type) app.add_node(desc_returns) - app.add_node(desc_name) app.add_node(desc_parameterlist) app.add_node(desc_parameter) app.add_node(desc_optional) app.add_node(desc_annotation) - app.add_node(desc_content) + for n in SIG_ELEMENTS: app.add_node(n) + app.add_node(versionmodified) app.add_node(seealso) app.add_node(productionlist) diff --git a/sphinx/domains/cpp.py b/sphinx/domains/cpp.py index bb11138d6..51cdd3946 100644 --- a/sphinx/domains/cpp.py +++ b/sphinx/domains/cpp.py @@ -7395,11 +7395,9 @@ class CPPExprRole(SphinxRole): if asCode: # render the expression as inline code self.class_type = 'cpp-expr' - self.node_type: Type[TextElement] = nodes.literal else: # render the expression as inline text self.class_type = 'cpp-texpr' - self.node_type = nodes.inline def run(self) -> Tuple[List[Node], List[system_message]]: text = self.text.replace('\n', ' ') @@ -7407,20 +7405,19 @@ class CPPExprRole(SphinxRole): location=self.get_source_info(), config=self.config) # attempt to mimic XRefRole classes, except that... - classes = ['xref', 'cpp', self.class_type] try: ast = parser.parse_expression() except DefinitionError as ex: logger.warning('Unparseable C++ expression: %r\n%s', text, ex, location=self.get_source_info()) # see below - return [self.node_type(text, text, classes=classes)], [] + return [addnodes.desc_inline('cpp', text, text, classes=[self.class_type])], [] parentSymbol = self.env.temp_data.get('cpp:parent_symbol', None) if parentSymbol is None: parentSymbol = self.env.domaindata['cpp']['root_symbol'] # ...most if not all of these classes should really apply to the individual references, # not the container node - signode = self.node_type(classes=classes) + signode = addnodes.desc_inline('cpp', classes=[self.class_type]) ast.describe_signature(signode, 'markType', self.env, parentSymbol) return [signode], [] diff --git a/sphinx/themes/basic/static/basic.css_t b/sphinx/themes/basic/static/basic.css_t index 4af85bea9..f0ce51e4b 100644 --- a/sphinx/themes/basic/static/basic.css_t +++ b/sphinx/themes/basic/static/basic.css_t @@ -532,6 +532,12 @@ table.hlist td { font-style: italic; } +/* C++ specific styling */ + +.sig-inline.cpp-expr { + font-family: monospace; +} + /* -- other body styles ----------------------------------------------------- */ diff --git a/sphinx/writers/html5.py b/sphinx/writers/html5.py index e3a28f85d..1c81584e3 100644 --- a/sphinx/writers/html5.py +++ b/sphinx/writers/html5.py @@ -117,6 +117,12 @@ class HTML5Translator(SphinxTranslator, BaseTranslator): def depart_desc_content(self, node: Element) -> None: self.body.append('') + def visit_desc_inline(self, node: Element) -> None: + self.body.append(self.starttag(node, 'span', '')) + + def depart_desc_inline(self, node: Element) -> None: + self.body.append('') + # Nodes for high-level structure in signatures ##############################################