From 4b6b54c73a5cfe0d6411dde8f7840de2c70b85d4 Mon Sep 17 00:00:00 2001 From: David Selassie Date: Wed, 10 Jan 2024 13:35:01 -0800 Subject: [PATCH] `autodoc2_module_summary = False` should still print non-summary API When `autodoc2_module_summary = False`, each module's page only includes the "Submodules" heading at the top and no other API documentation. I assume this is unintended, and the "summary" being referenced in this config option should only be the tables of each item type at the top of each module. I think this might have been an off-by-one indentation level error? The code to render the non-summary parts was accidentally indented to the level of the summary check `if`. If the existing behavior is the intended behavior of this config option, let me know and maybe we can change this to better document what the behavior should be. I didn't include any tests because I didn't see a pattern for handling combinations of config options, but I did test manually. If you want me to add something that tests this in isolation, let me know. Thanks! --- src/autodoc2/config.py | 2 +- src/autodoc2/render/myst_.py | 6 +++--- src/autodoc2/render/rst_.py | 6 +++--- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/src/autodoc2/config.py b/src/autodoc2/config.py index 0970e6e..f0ce8e7 100644 --- a/src/autodoc2/config.py +++ b/src/autodoc2/config.py @@ -365,7 +365,7 @@ class Config: module_summary: bool = dc.field( default=True, metadata={ - "help": "Whether to include a per-module summary.", + "help": "Whether to include tables at the top of each module with the one line summary of each item", "sphinx_type": bool, "category": "render", }, diff --git a/src/autodoc2/render/myst_.py b/src/autodoc2/render/myst_.py index 39b1623..54b4e28 100644 --- a/src/autodoc2/render/myst_.py +++ b/src/autodoc2/render/myst_.py @@ -166,9 +166,9 @@ def render_package(self, item: ItemData) -> t.Iterable[str]: ) yield "" - yield from ["### API", ""] - for name in visible_children: - yield from self.render_item(name) + yield from ["### API", ""] + for name in visible_children: + yield from self.render_item(name) def render_module(self, item: ItemData) -> t.Iterable[str]: """Create the content for a module.""" diff --git a/src/autodoc2/render/rst_.py b/src/autodoc2/render/rst_.py index 1a196f9..17b4b2e 100644 --- a/src/autodoc2/render/rst_.py +++ b/src/autodoc2/render/rst_.py @@ -159,9 +159,9 @@ def render_package(self, item: ItemData) -> t.Iterable[str]: ) yield "" - yield from ["API", "~~~", ""] - for name in visible_children: - yield from self.render_item(name) + yield from ["API", "~~~", ""] + for name in visible_children: + yield from self.render_item(name) def render_module(self, item: ItemData) -> t.Iterable[str]: """Create the content for a module."""