docs(dpa-adapt): fix Input Formats numbering and cap CLI section depth

- input_formats: drop the manual "1./2./3." heading prefixes that doubled
  with Sphinx auto-numbering (e.g. "9.2.1. 1. SMILES Tables (CSV)").
- conf.py: cap auto-generated CLI reference section numbering at depth 5
  via a doctree-resolved hook, so sphinx-argparse's deep subcommand
  nesting no longer renders numbers like "9.3.3.6.3.1.1.". Scoped to the
  dpa_adapt/cli page only; other pages and the global TOC are untouched.

Author: zirenjin

doc/conf.py

@@ -7,6 +7,10 @@
 
 # -- Path setup --------------------------------------------------------------
 
+from __future__ import (
+    annotations,
+)
+
 import datetime
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -224,3 +228,54 @@
 bibtex_bibfiles = ["../CITATIONS.bib"]
 
 remove_from_toctrees = ["autoapi/**/*", "API_CC/*", "api_c/*", "api_core/*"]
+
+
+# Auto-generated CLI reference pages (sphinx-argparse) nest a section per
+# subcommand and per argument group. Under the global ``:numbered:`` toctree
+# this explodes into unhelpful deep numbers (e.g. ``9.3.3.6.3.1.1.``). Cap the
+# section numbering at the given depth (number of dotted components); headings
+# deeper than that are left unnumbered. Only the listed pages are affected.
+from typing import (
+    TYPE_CHECKING,
+)
+
+from docutils import (
+    nodes,
+)
+
+if TYPE_CHECKING:
+    from sphinx.application import (
+        Sphinx,
+    )
+
+cli_secnumber_max_depth = {
+    "dpa_adapt/cli": 5,
+}
+
+
+def _cap_cli_secnumbers(app: Sphinx, doctree: nodes.document, docname: str) -> None:
+    """Drop section numbers below ``cli_secnumber_max_depth`` for CLI pages."""
+    max_depth = cli_secnumber_max_depth.get(docname)
+    if max_depth is None:
+        return
+    secnumbers = app.env.toc_secnumbers.get(docname)
+    if not secnumbers:
+        return
+    # The empty anchor "" holds the page chapter number (e.g. ``(9, 3)``).
+    # It must be dropped from the map, otherwise the writer falls back to it for
+    # the now-unnumbered deep sections; re-attach it to the page title instead.
+    page_number = secnumbers.get("")
+    app.env.toc_secnumbers[docname] = {
+        anchor: number
+        for anchor, number in secnumbers.items()
+        if anchor != "" and len(number) <= max_depth
+    }
+    if page_number:
+        for title in doctree.findall(nodes.title):
+            title["secnumber"] = page_number
+            break
+
+
+def setup(app: Sphinx) -> dict[str, bool]:
+    app.connect("doctree-resolved", _cap_cli_secnumbers)
+    return {"parallel_read_safe": True, "parallel_write_safe": True}

doc/dpa_adapt/input_formats.md

@@ -12,7 +12,7 @@ auto-detect the input type and route it to the correct pipeline:
 **formula table** → random doping from a POSCAR template,
 **structure files** → dpdata (auto-detect or explicit `--fmt`).
 
-## 1. SMILES Tables (CSV)
+## SMILES Tables (CSV)
 
 **Trigger:** file extension `.csv` **and** a SMILES column.
 By default, the converter reads `SMILES`/`smiles`; use `--smiles-col` for
@@ -46,7 +46,7 @@ dpaad data convert --input data.csv --output ./npy --fmt smiles \
     --split-seed 42 --conformer-seed 43
 ```
 
-## 2. Formula Tables (CSV/TXT + POSCAR Template)
+## Formula Tables (CSV/TXT + POSCAR Template)
 
 **Trigger:** `--fmt formula`. Reads a table of elemental composition formulas
 (e.g. `Ni0.65Gd0.15O2H1`) and a template POSCAR, then generates doped
@@ -91,7 +91,7 @@ dpa-adapt data convert --input compositions.txt --output ./npy --fmt formula \
     --poscar template.POSCAR --formula-col 0 --property-col 1
 ```
 
-## 3. Structure Files via dpdata
+## Structure Files via dpdata
 
 **Trigger:** inputs not routed to the SMILES or formula pipelines. This means
 `--fmt` is neither `smiles` nor `formula`; when `--fmt` is omitted, CSV inputs