fix: name the Python reference section python in ref_section_order:

docs/great-docs.yml

@@ -290,6 +290,14 @@ exclude:
   - create_default_config
   - load_config
 
+# Reference Section Order
+# -----------------------
+# Show the CLI first in the Reference area, then the Python API and MCP Server
+ref_section_order:
+  - cli
+  - python
+  - mcp
+
 # API Reference Structure
 # -----------------------
 # Explicit control over API reference organization

docs/user_guide/05-configuration.qmd

@@ -797,11 +797,11 @@ ordering of reference pages:
 ```{.yaml filename="great-docs.yml"}
 ref_section_order:
   - cli
-  - api
+  - python
   - mcp
 ```
 
-Valid values are `api`, `cli`, and `mcp`. Sections listed here that don't exist in your project are
+Valid values are `python`, `cli`, and `mcp`. Sections listed here that don't exist in your project are
 silently ignored, so it's safe to include `mcp` even if your package has no MCP server. Sections not
 listed are appended at the end in the default order. The navbar "Reference" link will point to
 whichever section is first.
@@ -1157,7 +1157,7 @@ navbar_order:
 # Reference Section Order (within the Reference area)
 ref_section_order:
   - cli
-  - api
+  - python
   - mcp
 
 # API Reference Structure

great_docs/assets/great-docs.default.yml

@@ -202,9 +202,9 @@ mcp:
 # Reference Section Order
 # -----------------------
 # Controls the display order of API subsections (the switcher tabs) in the
-# Reference area. Valid values: "api", "cli", "mcp". Sections listed here
+# Reference area. Valid values: "python", "cli", "mcp". Sections listed here
 # that don't exist in the project are silently ignored. When empty or omitted,
-# the default order is: api, cli, mcp.
+# the default order is: python, cli, mcp.
 ref_section_order: []
 
 # Dark Mode Toggle

great_docs/config.py

@@ -1422,7 +1422,13 @@ def navbar_order(self) -> list[str] | None:
 
     @property
     def ref_section_order(self) -> list[str] | None:
-        """Custom display order for reference subsection tabs (api, cli, mcp)."""
+        """
+        Custom display order for reference subsection tabs
+
+        Users name sections `python`, `cli` and `mcp`; `api` is still accepted
+        as an alias of `python`. The result holds the internal section ids
+        (`api`, `cli`, `mcp`), with unknown names and duplicates dropped.
+        """
         try:
             raw = self["ref_section_order"]
         except KeyError:
@@ -1431,7 +1437,12 @@ def ref_section_order(self) -> list[str] | None:
             items = cast("list[object]", raw)
             strings = [item for item in items if isinstance(item, str)]
             if len(strings) == len(items):
-                valid = [s for s in strings if s in ("api", "cli", "mcp")]
+                section_ids = {"python": "api", "api": "api", "cli": "cli", "mcp": "mcp"}
+                valid: list[str] = []
+                for name in strings:
+                    section_id = section_ids.get(name)
+                    if section_id and section_id not in valid:
+                        valid.append(section_id)
                 return valid if valid else None
         return None
 

test-packages/synthetic/catalog.py

@@ -2336,9 +2336,9 @@
         "`d2-<hash>-{light,dark}.svg` files copied into the site."
     ),
     "gdtest_ref_section_order": (
-        "CLI-first package with ref_section_order: [cli, api, mcp] in config. "
-        "The reference switcher tabs should appear CLI-first (cli,api) instead "
-        "of the default (api,cli). The data-gd-ref-sections body attribute "
+        "CLI-first package with ref_section_order: [mcp, cli, python] in config. "
+        "The reference switcher tabs should appear CLI-first instead of the "
+        "default (Python first). The data-gd-ref-sections body attribute "
         "should be 'cli,api' since there is no MCP server."
     ),
     "gdtest_mermaid": (

test-packages/synthetic/specs/gdtest_ref_section_order.py

@@ -3,9 +3,10 @@
 
 Dimensions: A1, B1, C1, D1, E1+E6, F6, G1, H7
 Focus: ref_section_order config key. The reference switcher tabs should
-appear in the order specified by the config (cli, api) instead of the
-default (api, cli). The data-gd-ref-sections body attribute should
-reflect this custom ordering.
+appear in the order specified by the config (cli, python) instead of the
+default (python, cli). The config also lists `mcp`, which this package doesn't
+have, to show that absent sections are skipped without an error. The
+data-gd-ref-sections body attribute should reflect this custom ordering.
 """
 
 SPEC = {
@@ -104,7 +105,7 @@ def list() -> None:
         "mcp": {
             "enabled": False,
         },
-        "ref_section_order": ["cli", "api"],
+        "ref_section_order": ["mcp", "cli", "python"],
     },
     "expected": {
         "detected_name": "gdtest-ref-section-order",
@@ -115,7 +116,7 @@ def list() -> None:
         "section_titles": ["Classes", "Functions"],
         "has_user_guide": False,
         "cli_enabled": True,
-        "ref_section_order": ["cli", "api"],
+        "ref_section_order": ["mcp", "cli", "python"],
         "coverage_exclude": ["nodoc", "bigcl", "ug", "supp", "hdg"],
     },
 }

tests/test_config.py

@@ -1943,11 +1943,19 @@ def test_default_none(self, tmp_path):
         assert Config(tmp_path).ref_section_order is None
 
     def test_valid_list(self, tmp_path):
+        cfg = _make_config(tmp_path, "ref_section_order:\n  - cli\n  - python\n  - mcp\n")
+        assert cfg.ref_section_order == ["cli", "api", "mcp"]
+
+    def test_api_alias_of_python(self, tmp_path):
         cfg = _make_config(tmp_path, "ref_section_order:\n  - cli\n  - api\n  - mcp\n")
         assert cfg.ref_section_order == ["cli", "api", "mcp"]
 
+    def test_duplicates_dropped(self, tmp_path):
+        cfg = _make_config(tmp_path, "ref_section_order:\n  - python\n  - cli\n  - api\n")
+        assert cfg.ref_section_order == ["api", "cli"]
+
     def test_filters_invalid_values(self, tmp_path):
-        cfg = _make_config(tmp_path, "ref_section_order:\n  - cli\n  - bogus\n  - api\n")
+        cfg = _make_config(tmp_path, "ref_section_order:\n  - cli\n  - bogus\n  - python\n")
         assert cfg.ref_section_order == ["cli", "api"]
 
     def test_all_invalid_returns_none(self, tmp_path):

tests/test_gdg_rendered.py

@@ -11877,7 +11877,11 @@ def test_DED_sidebar_sections_expanded_by_css():
 
 @pytest.mark.dedicated
 def test_DED_ref_section_order_cli_first():
-    """gdtest_ref_section_order: data-gd-ref-sections has cli before api."""
+    """gdtest_ref_section_order: data-gd-ref-sections has cli before api.
+
+    The config lists `mcp` first, but the package has no MCP server, so it is
+    left out rather than raising an error.
+    """
     pkg = "gdtest_ref_section_order"
     if not _has_rendered_site(pkg):
         pytest.skip(f"{pkg} not rendered")