DOCS: API docs ToC more levels (#5714)

* wip

* tidy up config

* wip

* set show_toc_level to 2 (same as default)

* add whatsnew

docs/src/conf.py

@@ -195,9 +195,17 @@ 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"
-autodoc_default_flags = ["show-inheritance"]
+# 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,
+    "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"
@@ -292,6 +300,7 @@ def _dotv(version):
     "footer_start": ["copyright", "sphinx-version"],
     "footer_end": ["custom_footer"],
     "navigation_depth": 3,
+    "show_toc_level": 2,
     "show_prev_next": True,
     "navbar_align": "content",
     # removes the search box from the top bar
@@ -319,7 +328,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"],

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
 ===========