[rst] Add level option to rubric directive

sphinx/directives/patches.py

@@ -176,12 +176,38 @@ def add_target(self, ret: list[Node]) -> None:
         ret.insert(0, target)
 
 
+class Rubric(SphinxDirective):
+    """A patch of the docutils' :rst:dir:`rubric` directive,
+    which adds a level option to specify the heading level of the rubric.
+    """
+
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = True
+    option_spec = {
+        'class': directives.class_option,
+        'name': directives.unchanged,
+        'level': lambda c: directives.choice(c, ('1', '2', '3', '4', '5')),
+    }
+
+    def run(self) -> list[Node]:
+        set_classes(self.options)
+        rubric_text = self.arguments[0]
+        textnodes, messages = self.parse_inline(rubric_text, lineno=self.lineno)
+        rubric = nodes.rubric(rubric_text, '', *textnodes, **self.options)
+        self.add_name(rubric)
+        if 'level' in self.options:
+            rubric['level'] = int(self.options['level'])
+        return [rubric, *messages]
+
+
 def setup(app: Sphinx) -> ExtensionMetadata:
     directives.register_directive('figure', Figure)
     directives.register_directive('meta', Meta)
     directives.register_directive('csv-table', CSVTable)
     directives.register_directive('code', Code)
     directives.register_directive('math', MathDirective)
+    directives.register_directive('rubric', Rubric)
 
     return {
         'version': 'builtin',

sphinx/writers/html5.py

@@ -510,6 +510,20 @@ def depart_title(self, node: Element) -> None:
 
         super().depart_title(node)
 
+    # overwritten
+    def visit_rubric(self, node: Element) -> None:
+        if level := node.get("level"):
+            self.body.append(self.starttag(node, f'h{level}', '', CLASS='rubric'))
+        else:
+            super().visit_rubric(node)
+
+    # overwritten
+    def depart_rubric(self, node: Element) -> None:
+        if level := node.get("level"):
+            self.body.append(f'</h{level}>\n')
+        else:
+            super().depart_rubric(node)
+
     # overwritten
     def visit_literal_block(self, node: Element) -> None:
         if node.rawsource != node.astext():

sphinx/writers/latex.py

@@ -958,7 +958,14 @@ def depart_seealso(self, node: Element) -> None:
     def visit_rubric(self, node: Element) -> None:
         if len(node) == 1 and node.astext() in ('Footnotes', _('Footnotes')):
             raise nodes.SkipNode
-        self.body.append(r'\subsubsection*{')
+        tag = {
+            1: 'section',
+            2: 'subsection',
+            3: 'subsubsection',
+            4: 'paragraph',
+            5: 'subparagraph',
+        }.get(node.get('level', 0), 'subsubsection')
+        self.body.append(rf'\{tag}*{{')
         self.context.append('}' + CR)
         self.in_title = 1
 

tests/roots/test-markup-rubric/index.rst

@@ -5,3 +5,7 @@ test-markup-rubric
 
 .. rubric:: This is
    a multiline rubric
+
+.. rubric:: A rubric with a heading level
+   :level: 2
+   :class: my-class

tests/test_builders/test_build_html_5_output.py

@@ -275,3 +275,11 @@ def checker(nodes):
 def test_html5_output(app, cached_etree_parse, fname, path, check):
     app.build()
     check_xpath(cached_etree_parse(app.outdir / fname), fname, path, check)
+
+
+@pytest.mark.sphinx('html', testroot='markup-rubric')
+def test_html5_rubric(app):
+    app.build()
+    content = (app.outdir / 'index.html').read_text(encoding='utf8')
+    assert '<p class="rubric">This is a rubric</p>' in content
+    assert '<h2 class="my-class rubric">A rubric with a heading level</h2>' in content

tests/test_builders/test_build_latex.py

@@ -1759,3 +1759,11 @@ def test_one_parameter_per_line(app, status, warning):
     assert ('\\pysiglinewithargsret{\\sphinxbfcode{\\sphinxupquote{hello}}}' in result)
 
     assert ('\\pysigwithonelineperarg{\\sphinxbfcode{\\sphinxupquote{foo}}}' in result)
+
+
+@pytest.mark.sphinx('latex', testroot='markup-rubric')
+def test_latex_rubric(app):
+    app.build()
+    content = (app.outdir / 'test.tex').read_text(encoding='utf8')
+    assert r'\subsubsection*{This is a rubric}' in content
+    assert r'\subsection*{A rubric with a heading level}' in content

tests/test_builders/test_build_texinfo.py

@@ -43,6 +43,7 @@ def test_texinfo_rubric(app, status, warning):
     output = (app.outdir / 'python.texi').read_text(encoding='utf8')
     assert '@heading This is a rubric' in output
     assert '@heading This is a multiline rubric' in output
+    assert '@heading A rubric with a heading level' in output
 
 
 @pytest.mark.sphinx('texinfo', testroot='markup-citation')