Support content in py:module and js:module

Author: AA-Turner

sphinx/domains/javascript.py

@@ -249,7 +249,7 @@ class JSModule(SphinxDirective):
     :param mod_name: Module name
     """
 
-    has_content = False
+    has_content = True
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = False
@@ -258,10 +258,14 @@ class JSModule(SphinxDirective):
     }
 
     def run(self) -> List[Node]:
+        content_node = nodes.Element()
+        self.state.nested_parse(self.content, self.content_offset, content_node,
+                                match_titles=True)
+
         mod_name = self.arguments[0].strip()
         self.env.ref_context['js:module'] = mod_name
         noindex = 'noindex' in self.options
-        ret: List[Node] = []
+        ret: List[Node] = [*content_node.children]
         if not noindex:
             domain = cast(JavaScriptDomain, self.env.get_domain('js'))
 

sphinx/domains/python.py

@@ -28,9 +28,10 @@
 from sphinx.roles import XRefRole
 from sphinx.util import logging
 from sphinx.util.docfields import Field, GroupedField, TypedField
-from sphinx.util.docutils import SphinxDirective
+from sphinx.util.docutils import SphinxDirective, switch_source_input
 from sphinx.util.inspect import signature_from_str
-from sphinx.util.nodes import find_pending_xref_condition, make_id, make_refnode
+from sphinx.util.nodes import (find_pending_xref_condition, make_id, make_refnode,
+                               nested_parse_with_titles)
 from sphinx.util.typing import OptionSpec, TextlikeNode
 
 logger = logging.getLogger(__name__)
@@ -967,7 +968,7 @@ class PyModule(SphinxDirective):
     Directive to mark description of a new module.
     """
 
-    has_content = False
+    has_content = True
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = False
@@ -984,7 +985,14 @@ def run(self) -> List[Node]:
         modname = self.arguments[0].strip()
         noindex = 'noindex' in self.options
         self.env.ref_context['py:module'] = modname
-        ret: List[Node] = []
+
+        content_node: Element = nodes.section()
+        with switch_source_input(self.state, self.content):
+            # necessary so that the child nodes get the right source/line set
+            content_node.document = self.state.document
+            nested_parse_with_titles(self.state, self.content, content_node)
+
+        ret: List[Node] = [*content_node.children]
         if not noindex:
             # note module to the domain
             node_id = make_id(self.env, self.state.document, 'module', modname)

sphinx/ext/autodoc/__init__.py

@@ -978,6 +978,15 @@ def __init__(self, *args: Any) -> None:
         merge_members_option(self.options)
         self.__all__: Optional[Sequence[str]] = None
 
+    def add_content(self, more_content: Optional[StringList]) -> None:
+        old_indent = self.indent
+        self.indent += '   '
+        super().add_content(None)
+        self.indent = old_indent
+        if more_content:
+            for line, src in zip(more_content.data, more_content.items):
+                self.add_line(line, src[0], src[1])
+
     @classmethod
     def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any
                             ) -> bool:

tests/test_ext_autodoc_automodule.py

@@ -19,7 +19,7 @@ def test_empty_all(app):
         '',
         '.. py:module:: target.empty_all',
         '',
-        'docsting of empty_all module.',
+        '   docsting of empty_all module.',
         '',
     ]