From 75468464dd6507b8ed3c894531fbc25a1168d5e5 Mon Sep 17 00:00:00 2001 From: Tremain Knight <2108488+tkknight@users.noreply.github.com> Date: Thu, 28 Dec 2023 17:12:23 +0000 Subject: [PATCH 1/5] wip --- docs/src/conf.py | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/docs/src/conf.py b/docs/src/conf.py index dab4c9052d..f683a3920a 100644 --- a/docs/src/conf.py +++ b/docs/src/conf.py @@ -195,7 +195,23 @@ def _dotv(version): # api generation configuration autodoc_member_order = "alphabetical" -autodoc_default_flags = ["show-inheritance"] + +# The supported options are +# 'members', 'member-order', 'undoc-members', +# 'private-members', 'special-members', 'inherited-members', +# 'show-inheritance', 'ignore-module-all', 'imported-members', +# 'exclude-members', 'class-doc-from' and 'no-value'. +#autodoc_default_flags = ["show-inheritance"] +autodoc_default_options = { + 'members': True, + 'member-order': "alphabetical", + 'undoc-members': True, + 'special-members': True, + 'inherited-members': True, + 'imported-members': True, + 'show-inheritance': True, +} + # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_typehints autodoc_typehints = "none" @@ -291,6 +307,7 @@ def _dotv(version): "footer_end": ["custom_footer"], "collapse_navigation": True, "navigation_depth": 3, + "show_toc_level": 3, "show_prev_next": True, "navbar_align": "content", # removes the search box from the top bar @@ -318,7 +335,6 @@ def _dotv(version): }, ], "use_edit_page_button": True, - "show_toc_level": 1, # Omit `theme-switcher` from navbar_end below to disable it # Info: https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/light-dark.html#configure-default-theme-mode # "navbar_end": ["navbar-icon-links"], From 320b81594bf4ec9e28e3c38ad0b003e0b72b493e Mon Sep 17 00:00:00 2001 From: Tremain Knight <2108488+tkknight@users.noreply.github.com> Date: Fri, 29 Dec 2023 17:01:24 +0000 Subject: [PATCH 2/5] tidy up config --- docs/src/conf.py | 27 +++++++++------------------ 1 file changed, 9 insertions(+), 18 deletions(-) diff --git a/docs/src/conf.py b/docs/src/conf.py index f683a3920a..ed96c2a0f5 100644 --- a/docs/src/conf.py +++ b/docs/src/conf.py @@ -193,31 +193,22 @@ def _dotv(version): # See https://www.sphinx-doc.org/en/master/usage/extensions/todo.html todo_include_todos = True -# api generation configuration -autodoc_member_order = "alphabetical" - -# The supported options are -# 'members', 'member-order', 'undoc-members', -# 'private-members', 'special-members', 'inherited-members', -# 'show-inheritance', 'ignore-module-all', 'imported-members', -# 'exclude-members', 'class-doc-from' and 'no-value'. -#autodoc_default_flags = ["show-inheritance"] +# sphinx.ext.autodocconfiguration --------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_default_options autodoc_default_options = { - 'members': True, - 'member-order': "alphabetical", - 'undoc-members': True, - 'special-members': True, - 'inherited-members': True, - 'imported-members': True, - 'show-inheritance': True, + "members": True, + "member-order": "alphabetical", + "undoc-members": True, + "private-members" : False, + "special-members": False, + "inherited-members": True, + "show-inheritance": True, } - # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_typehints autodoc_typehints = "none" autosummary_generate = True autosummary_imported_members = True -autopackage_name = ["iris"] autoclass_content = "both" modindex_common_prefix = ["iris"] From adaf10415eb2b3c956444db3f4d436befdc101a0 Mon Sep 17 00:00:00 2001 From: Tremain Knight <2108488+tkknight@users.noreply.github.com> Date: Wed, 24 Jan 2024 15:41:01 +0000 Subject: [PATCH 3/5] wip --- docs/src/conf.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/src/conf.py b/docs/src/conf.py index 57b4986b8f..2c54f70ac5 100644 --- a/docs/src/conf.py +++ b/docs/src/conf.py @@ -195,13 +195,13 @@ def _dotv(version): # See https://www.sphinx-doc.org/en/master/usage/extensions/todo.html todo_include_todos = True -# sphinx.ext.autodocconfiguration --------------------------------------------- +# sphinx.ext.autodoc configuration -------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_default_options autodoc_default_options = { "members": True, "member-order": "alphabetical", "undoc-members": True, - "private-members" : False, + "private-members": False, "special-members": False, "inherited-members": True, "show-inheritance": True, @@ -211,6 +211,7 @@ def _dotv(version): autodoc_typehints = "none" autosummary_generate = True autosummary_imported_members = True +autopackage_name = ["iris"] autoclass_content = "both" modindex_common_prefix = ["iris"] From 0261f36b428a35965f9037d288c8344bc49ac97b Mon Sep 17 00:00:00 2001 From: Tremain Knight <2108488+tkknight@users.noreply.github.com> Date: Wed, 24 Jan 2024 16:16:56 +0000 Subject: [PATCH 4/5] set show_toc_level to 2 (same as default) --- docs/src/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/conf.py b/docs/src/conf.py index 2c54f70ac5..a988fe24c4 100644 --- a/docs/src/conf.py +++ b/docs/src/conf.py @@ -300,7 +300,7 @@ def _dotv(version): "footer_start": ["copyright", "sphinx-version"], "footer_end": ["custom_footer"], "navigation_depth": 3, - "show_toc_level": 3, + "show_toc_level": 2, "show_prev_next": True, "navbar_align": "content", # removes the search box from the top bar From ae52c66c0349bb453713148f03922b4f2aa12ee1 Mon Sep 17 00:00:00 2001 From: Tremain Knight <2108488+tkknight@users.noreply.github.com> Date: Wed, 31 Jan 2024 10:52:27 +0000 Subject: [PATCH 5/5] add whatsnew --- docs/src/whatsnew/latest.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/src/whatsnew/latest.rst b/docs/src/whatsnew/latest.rst index dc661f5738..e711679a7f 100644 --- a/docs/src/whatsnew/latest.rst +++ b/docs/src/whatsnew/latest.rst @@ -172,6 +172,9 @@ This document explains the changes made to Iris for this release #. `@tkknight`_ added ruff documentation in the :ref:`developer_testing_ci` of the :ref:`developers_guide`. (:pull:`5701`) +#. `@tkknight`_ configured the API documentation to show 2 levels + for the ToC (Table of Contents) for each page. (:pull:`5714`) + 💼 Internal ===========