👌 Improve allow rendering in non-standalone mode

Author: chrisjsewell

docs/apidocs/autodoc2/autodoc2.render.base.rst

@@ -23,7 +23,7 @@ Classes
 API
 ~~~
 
-.. py:class:: RendererBase(db: autodoc2.db.Database, config: autodoc2.config.Config, warn: typing.Callable[[str, autodoc2.utils.WarningSubtypes], None] | None = None, resolved_all: dict[str, autodoc2.utils.ResolvedDict] | None = None)
+.. py:class:: RendererBase(db: autodoc2.db.Database, config: autodoc2.config.Config, warn: typing.Callable[[str, autodoc2.utils.WarningSubtypes], None] | None = None, resolved_all: dict[str, autodoc2.utils.ResolvedDict] | None = None, standalone: bool = True)
    :canonical: autodoc2.render.base.RendererBase
 
    Bases: :py:obj:`abc.ABC`
@@ -62,6 +62,13 @@ API
       .. autodoc2-docstring:: autodoc2.render.base.RendererBase.config
          :parser: 
 
+   .. py:property:: standalone
+      :canonical: autodoc2.render.base.RendererBase.standalone
+      :type: bool
+
+      .. autodoc2-docstring:: autodoc2.render.base.RendererBase.standalone
+         :parser: 
+
    .. py:method:: warn(msg: str, type_: autodoc2.utils.WarningSubtypes = WarningSubtypes.RENDER_ERROR) -> None
       :canonical: autodoc2.render.base.RendererBase.warn
 

docs/apidocs/autodoc2/autodoc2.render.myst_.rst

@@ -40,7 +40,7 @@ API
 
    .. autodoc2-docstring:: autodoc2.render.myst_._RE_DELIMS
 
-.. py:class:: MystRenderer(db: autodoc2.db.Database, config: autodoc2.config.Config, warn: typing.Callable[[str, autodoc2.utils.WarningSubtypes], None] | None = None, resolved_all: dict[str, autodoc2.utils.ResolvedDict] | None = None)
+.. py:class:: MystRenderer(db: autodoc2.db.Database, config: autodoc2.config.Config, warn: typing.Callable[[str, autodoc2.utils.WarningSubtypes], None] | None = None, resolved_all: dict[str, autodoc2.utils.ResolvedDict] | None = None, standalone: bool = True)
    :canonical: autodoc2.render.myst_.MystRenderer
 
    Bases: :py:obj:`autodoc2.render.base.RendererBase`

docs/apidocs/autodoc2/autodoc2.render.rst_.rst

@@ -40,7 +40,7 @@ API
 
    .. autodoc2-docstring:: autodoc2.render.rst_._RE_DELIMS
 
-.. py:class:: RstRenderer(db: autodoc2.db.Database, config: autodoc2.config.Config, warn: typing.Callable[[str, autodoc2.utils.WarningSubtypes], None] | None = None, resolved_all: dict[str, autodoc2.utils.ResolvedDict] | None = None)
+.. py:class:: RstRenderer(db: autodoc2.db.Database, config: autodoc2.config.Config, warn: typing.Callable[[str, autodoc2.utils.WarningSubtypes], None] | None = None, resolved_all: dict[str, autodoc2.utils.ResolvedDict] | None = None, standalone: bool = True)
    :canonical: autodoc2.render.rst_.RstRenderer
 
    Bases: :py:obj:`autodoc2.render.base.RendererBase`

src/autodoc2/render/base.py

@@ -27,10 +27,19 @@ def __init__(
         config: Config,
         warn: t.Callable[[str, WarningSubtypes], None] | None = None,
         resolved_all: dict[str, ResolvedDict] | None = None,
+        standalone: bool = True,
     ) -> None:
-        """Initialise the renderer."""
+        """Initialise the renderer.
+
+        :param db: The database to obtain objects from.
+        :param config: The configuration.
+        :param warn: A function to call when a warning is encountered.
+        :param resolved_all: A dictionary of full_name -> __all__ resolution.
+        :param standalone: If True, this renderer is being used to create a standalone document
+        """
         self._db = db
         self._config = config
+        self._standalone = standalone
         self._warn = warn or (lambda msg, type_: None)
         self._resolved_all = resolved_all
         self._resolve_all_warned: set[str] = set()
@@ -43,6 +52,11 @@ def config(self) -> Config:
         """The configuration."""
         return self._config
 
+    @property
+    def standalone(self) -> bool:
+        """If True, this renderer is being used to create a standalone document."""
+        return self._standalone
+
     def warn(
         self, msg: str, type_: WarningSubtypes = WarningSubtypes.RENDER_ERROR
     ) -> None:

src/autodoc2/render/myst_.py

@@ -66,7 +66,7 @@ def enclosing_backticks(text: str) -> str:
 
     def render_package(self, item: ItemData) -> t.Iterable[str]:
         """Create the content for a package."""
-        if self.is_hidden(item):
+        if self.standalone and self.is_hidden(item):
             yield from ["---", "orphan: true", "---", ""]
 
         full_name = item["full_name"]
@@ -164,9 +164,6 @@ def render_module(self, item: ItemData) -> t.Iterable[str]:
 
     def render_function(self, item: ItemData) -> t.Iterable[str]:
         """Create the content for a function."""
-        if self.is_hidden(item):
-            return
-
         short_name = item["full_name"].split(".")[-1]
         show_annotations = self.show_annotations(item)
         sig = f"{short_name}({self.format_args(item['args'], show_annotations)})"
@@ -196,9 +193,6 @@ def render_exception(self, item: ItemData) -> t.Iterable[str]:
 
     def render_class(self, item: ItemData) -> t.Iterable[str]:
         """Create the content for a class."""
-        if self.is_hidden(item):
-            return
-
         short_name = item["full_name"].split(".")[-1]
         constructor = self.get_item(f"{item['full_name']}.__init__")
         sig = short_name
@@ -270,9 +264,6 @@ def render_class(self, item: ItemData) -> t.Iterable[str]:
 
     def render_property(self, item: ItemData) -> t.Iterable[str]:
         """Create the content for a property."""
-        if self.is_hidden(item):
-            return
-
         short_name = item["full_name"].split(".")[-1]
         yield f"````{{py:property}} {short_name}"
         yield f":canonical: {item['full_name']}"
@@ -295,9 +286,6 @@ def render_property(self, item: ItemData) -> t.Iterable[str]:
 
     def render_method(self, item: ItemData) -> t.Iterable[str]:
         """Create the content for a method."""
-        if self.is_hidden(item):
-            return
-
         short_name = item["full_name"].split(".")[-1]
         show_annotations = self.show_annotations(item)
         sig = f"{short_name}({self.format_args(item['args'], show_annotations, ignore_self='self')})"
@@ -329,9 +317,6 @@ def render_attribute(self, item: ItemData) -> t.Iterable[str]:
 
     def render_data(self, item: ItemData) -> t.Iterable[str]:
         """Create the content for a data item."""
-        if self.is_hidden(item):
-            return
-
         short_name = item["full_name"].split(".")[-1]
 
         yield f"````{{py:{item['type']}}} {short_name}"

src/autodoc2/render/rst_.py

@@ -58,7 +58,7 @@ def generate_summary(self, items: list[ItemData]) -> t.Iterable[str]:
 
     def render_package(self, item: ItemData) -> t.Iterable[str]:
         """Create the content for a package."""
-        if self.is_hidden(item):
+        if self.standalone and self.is_hidden(item):
             yield from [":orphan:", ""]
 
         full_name = item["full_name"]
@@ -154,9 +154,6 @@ def render_module(self, item: ItemData) -> t.Iterable[str]:
 
     def render_function(self, item: ItemData) -> t.Iterable[str]:
         """Create the content for a function."""
-        if self.is_hidden(item):
-            return
-
         short_name = item["full_name"].split(".")[-1]
         show_annotations = self.show_annotations(item)
         sig = f"{short_name}({self.format_args(item['args'], show_annotations)})"
@@ -184,9 +181,6 @@ def render_exception(self, item: ItemData) -> t.Iterable[str]:
 
     def render_class(self, item: ItemData) -> t.Iterable[str]:
         """Create the content for a class."""
-        if self.is_hidden(item):
-            return
-
         short_name = item["full_name"].split(".")[-1]
         constructor = self.get_item(f"{item['full_name']}.__init__")
         sig = short_name
@@ -240,9 +234,6 @@ def render_class(self, item: ItemData) -> t.Iterable[str]:
 
     def render_property(self, item: ItemData) -> t.Iterable[str]:
         """Create the content for a property."""
-        if self.is_hidden(item):
-            return
-
         short_name = item["full_name"].split(".")[-1]
         yield f".. py:property:: {short_name}"
         yield f"   :canonical: {item['full_name']}"
@@ -261,9 +252,6 @@ def render_property(self, item: ItemData) -> t.Iterable[str]:
 
     def render_method(self, item: ItemData) -> t.Iterable[str]:
         """Create the content for a method."""
-        if self.is_hidden(item):
-            return
-
         short_name = item["full_name"].split(".")[-1]
         show_annotations = self.show_annotations(item)
         sig = f"{short_name}({self.format_args(item['args'], show_annotations, ignore_self='self')})"
@@ -292,9 +280,6 @@ def render_attribute(self, item: ItemData) -> t.Iterable[str]:
 
     def render_data(self, item: ItemData) -> t.Iterable[str]:
         """Create the content for a data item."""
-        if self.is_hidden(item):
-            return
-
         short_name = item["full_name"].split(".")[-1]
         yield f".. py:{item['type']}:: {short_name}"
         yield f"   :canonical: {item['full_name']}"