Centralise nested directive checking

Author: chrisjsewell

docs/_static/custom.css

@@ -1,4 +1,7 @@
 /* required for nice formatting with furo */
+.need_container {
+    overflow-y: scroll;
+}
 table.need {
     background-color: var(--color-code-background);
 }

docs/index.rst

@@ -19,7 +19,8 @@ This package is intended to bring API documentation for Rust crates to Sphinx:
 - Integrates with the Sphinx cross-referencing system and
   :external:doc:`intersphinx <usage/extensions/intersphinx>` indexing.
 
-- Supports writing docstrings for any valid Sphinx parser (reStructuredText, MyST markdown, ...)
+- Supports writing docstrings for any valid Sphinx parser
+  (reStructuredText, `MyST markdown <https://myst-parser.readthedocs.io>`__, ...)
 
 Installation
 ------------

python/sphinx_rust/directives/_core.py

@@ -41,7 +41,24 @@ def rust_domain(self) -> RustDomain:
     def cache_path(self) -> str:
         return str(self.env.rust_cache_path)  # type: ignore[attr-defined]
 
+    def is_nested(self, warn: bool = True) -> bool:
+        """Check if the directive is nested inside another directive.
+
+        If we are going to generate section nodes, then this is not allowed,
+        since it would break the documentation structure.
+        """
+        if warn and not self.state_machine.match_titles:
+            # we are going to generate section nodes, and they will not work
+            # if e.g. the directive is called from inside a directive
+            LOGGER.warning(
+                f"{self.name!r} directive can only be used at the root of the document",
+                type="rust",
+                subtype="root",
+            )
+        return self.state_machine.match_titles  # type: ignore[no-any-return]
+
     def create_section(self, title: str) -> nodes.section:
+        """Create a new section node."""
         section = nodes.section()
         self.set_source_info(section)
         section += nodes.title(text=title)

python/sphinx_rust/directives/crate.py

@@ -26,14 +26,7 @@ class RustCrateAutoDirective(RustAutoDirective):
     """Directive to auto-document a Rust crate."""
 
     def run(self) -> list[nodes.Node]:
-        if not self.state_machine.match_titles:
-            # we are going to generate section nodes, and they will not work
-            # if e.g. the directive is called from inside a directive
-            LOGGER.warning(
-                f"{self.name!r} directive can only be used at the root of the document",
-                type="rust",
-                subtype="root",
-            )
+        if self.is_nested():
             return []
 
         qualifier = self.arguments[0]

python/sphinx_rust/directives/enum.py

@@ -25,14 +25,7 @@ class RustEnumAutoDirective(RustAutoDirective):
     """Directive to auto-document a Rust enum."""
 
     def run(self) -> list[nodes.Node]:
-        if not self.state_machine.match_titles:
-            # we are going to generate section nodes, and they will not work
-            # if e.g. the directive is called from inside a directive
-            LOGGER.warning(
-                f"{self.name!r} directive can only be used at the root of the document",
-                type="rust",
-                subtype="root",
-            )
+        if self.is_nested():
             return []
 
         qualifier = self.arguments[0]

python/sphinx_rust/directives/module.py

@@ -27,14 +27,7 @@ class RustModuleAutoDirective(RustAutoDirective):
     """Directive to auto-document a Rust module."""
 
     def run(self) -> list[nodes.Node]:
-        if not self.state_machine.match_titles:
-            # we are going to generate section nodes, and they will not work
-            # if e.g. the directive is called from inside a directive
-            LOGGER.warning(
-                f"{self.name!r} directive can only be used at the root of the document",
-                type="rust",
-                subtype="root",
-            )
+        if self.is_nested():
             return []
 
         qualifier = self.arguments[0]

python/sphinx_rust/directives/struct.py

@@ -26,14 +26,7 @@ class RustStructAutoDirective(RustAutoDirective):
     """Directive to auto-document a Rust struct."""
 
     def run(self) -> list[nodes.Node]:
-        if not self.state_machine.match_titles:
-            # we are going to generate section nodes, and they will not work
-            # if e.g. the directive is called from inside a directive
-            LOGGER.warning(
-                f"{self.name!r} directive can only be used at the root of the document",
-                type="rust",
-                subtype="root",
-            )
+        if self.is_nested():
             return []
 
         qualifier = self.arguments[0]