From 6c7bf6139c61e1b11dd25cf55cf0608bb1376a88 Mon Sep 17 00:00:00 2001
From: tkknight <2108488+tkknight@users.noreply.github.com>
Date: Fri, 2 Feb 2024 12:16:18 +0000
Subject: [PATCH] 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             | 16 ++++++++++++----
 docs/src/whatsnew/latest.rst |  3 +++
 2 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/docs/src/conf.py b/docs/src/conf.py
index 0fa493bde1..a988fe24c4 100644
--- a/docs/src/conf.py
+++ b/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"],
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
 ===========