fixeria has uploaded this change for review.

View Change

docs/conf.py: silence autosectionlabel duplicate-label warnings

sphinxarg.ext generates generic sub-headings ("Named arguments",
"Positional arguments", "Sub-commands", "General options", ...) for
every argparse command and tool.  These repeat across many files and
trigger large numbers of autosectionlabel duplicate-label warnings.

Two-pronged fix:

* `autosectionlabel_maxdepth = 3` eliminates the depth-4+ warnings
  (sub-headings inside each individual command block).
* `suppress_warnings` per file silences the residual depth-3 collisions
  ("serial reader", "decode_hex", "sub-commands", ...) that still
  appear across tool documentation files.

Cross-references into these generic argparse-generated sections are not
a supported use-case, so suppressing the warnings is appropriate.

Change-Id: I9cdf2a4f6cbd435b16b90ab668205600ffd7c3b0
---
M docs/conf.py
1 file changed, 20 insertions(+), 0 deletions(-)

git pull ssh://gerrit.osmocom.org:29418/pysim refs/changes/43/42543/1

diff --git a/docs/conf.py b/docs/conf.py
index ef40070..13a66e5 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -64,3 +64,23 @@
 html_static_path = ['_static']
 
 autoclass_content = 'both'
+
+# sphinxarg.ext generates generic sub-headings ("Named arguments",
+# "Positional arguments", "Sub-commands", "General options", …) for every
+# argparse command/tool.  These repeat across many files and trigger masses
+# of autosectionlabel duplicate-label warnings.
+#
+# autosectionlabel_maxdepth = 3 eliminates most of them (depth-4+ sub-headings
+# inside each command block), but cross-file collisions at depth 3 ("serial
+# reader", "decode_hex", etc.) still slip through.  Suppress the residual
+# warnings per-file; cross-references into these sections are not a supported
+# use-case.
+autosectionlabel_maxdepth = 3
+suppress_warnings = [
+    'autosectionlabel.saip-tool',
+    'autosectionlabel.shell',
+    'autosectionlabel.smpp2sim',
+    'autosectionlabel.smpp-ota-tool',
+    'autosectionlabel.suci-keytool',
+    'autosectionlabel.trace',
+]

To view, visit change 42543. To unsubscribe, or for help writing mail filters, visit settings.