Refactor the extension to use a Sphinx Domain (Updated in 2025)

.pre-commit-config.yaml

@@ -33,4 +33,4 @@ repos:
         language: system
         entry: mypy
         types: [python]
-        exclude: ^docs/
+        exclude: ^(docs|test/roots)/

docs/changelog.rst

@@ -2,6 +2,33 @@
 Change log
 **********
 
+0.6.0
+#####
+
+The following enhancements to the HTML output are described on the :doc:`usage` page.
+
+* Optional command index.
+* Optional ``:index-groups:`` field to the directive for an command-by-group index.
+* A ``sphinxarg_full_subcommand_name`` option to print fully-qualified sub-command headings.
+  This option helps when more than one sub-command offers a ``create`` or ``list`` or other
+  repeated sub-command.
+* Each command heading is a domain-specific link target.
+  You can link to commands and sub-commands with the ``:ref:`` role, but this
+  release adds support for the domain-specific role like
+  ``:commands:command:`sample-directive-opts A` ``.
+  The ``:commands:command:`` role supports linking from other projects through the
+  intersphinx extension.
+
+Changes
+
+* Previously, common headings such as **Positional Arguments** were subject to a
+  process that made them unique by adding a ``_repeatX`` suffix to the HREF target.
+  This release continues to support those HREF targets as secondary targets so that
+  bookmarks continue to work.
+  However, this release prefers using fully-qualified HREF targets like
+  ``sample-directive-opts-positional-arguments`` as the primary HREF so that customers
+  are less likely to witness the ``_repeatX`` link in URLs.
+
 0.5.2
 #####
 

docs/conf.py

@@ -17,6 +17,7 @@
 
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3/', None),
+    'sphinx': ('https://www.sphinx-doc.org/', None),
 }
 
 # -- Options for HTML output ---------------------------------------------------

docs/usage.rst

@@ -1,3 +1,4 @@
+===========
 Basic usage
 ===========
 
@@ -75,6 +76,32 @@ working dir.
 
 That's it. Directives will render positional arguments, options and sub-commands.
 
+
+Config
+======
+
+The following ``conf.py`` config options are available, with their default values.
+The next sections will describe the options in more detail.
+
+.. code:: py
+
+   sphinxarg_full_subcommand_name = False
+
+   sphinxarg_build_commands_index = False
+   sphinxarg_commands_index_in_toctree = False
+
+   sphinxarg_build_commands_by_group_index = False
+   sphinxarg_commands_by_group_index_in_toctree = False
+   sphinxarg_commands_by_group_index_file_suffix = "by-group"
+   sphinxarg_commands_by_group_index_title = "Commands by Group"
+
+
+.. _about-subcommands:
+
+
+About Sub-Commands
+==================
+
 Sub-commands are limited to one level. But, you can always output help for subcommands separately:
 
 .. code:: rst
@@ -99,7 +126,7 @@ Nesting level is unlimited:
 
 
 Other useful directives
------------------------
+=======================
 
 :nodefault: Do not show any default values.
 
@@ -112,3 +139,115 @@ Other useful directives
 :nodescription: Do not parse the description, which can be useful if it contains text that could be incorrectly parse as reStructuredText.
 
 :passparser: This can be used if you don't have a function that returns an argument parser, but rather adds commands to it (``:func:`` is then that function).
+
+:index-groups: This option is related to grouping related commands in an index.
+
+
+Printing Fully Qualified Sub-Command Headings
+=============================================
+
+By default, when a command has sub-commands, such as ``fancytool install`` shown in the
+:ref:`about-subcommands` section, the heading for the sub-command does not include the command name.
+For instance, the the heading is **install** rather than **fancytool install**.
+
+If you prefer to show the full command, **fancytool install**, then you can enable
+the option in the ``conf.py`` for your project:
+
+.. code-block:: python
+
+   sphinxarg_full_subcommand_name = True
+
+
+Indices
+=======
+
+The extension supports two types of optional indices.
+The first type of index is a simple index that provides a list of all the commands in the project by fully qualified name and a link to each command.
+The second type of index enables you to group related commands into groups and then provide a list of the commands and a link to each command.
+By default, no index is created.
+
+Simple Command Index
+--------------------
+
+To enable the simple command index, add the following to the project ``conf.py`` file:
+
+.. code-block:: python
+
+    sphinxarg_build_commands_index = True
+    sphinxarg_commands_index_in_toctree = True
+
+The first option, ``build_commands_index``, instructs the extension to create the index.
+For an HTML build, the index is created with the file name ``commands-index.html`` in the output directory.
+You can reference the index from other files with the ``:ref:`commands-index``` markup.
+
+The second option, ``commands_index_in_toctree``, enables you to reference the the index in a ``toctree`` directive.
+By default, you cannot reference indices generated by extensions in a ``toctree``.
+When you enable this option, the extension creates a temporary file that is named ``commands-index.rst`` in the source directory of your project.
+Sphinx locates the temporary file and that makes it possible to reference the file in the ``toctree``.
+When the Sphinx build finishes, the extension removes the temporary file from the source directory.
+
+Commands by Group Index
+-----------------------
+
+To enable the more complex index, add the following to the project ``conf.py`` file:
+
+.. code-block:: python
+
+    sphinxarg_build_commands_by_group_index = True
+    sphinxarg_commands_by_group_index_in_toctree = True
+
+Add the ``:index-groups:`` option to the ``argparse`` directive in your documentation files.
+Specify one or more groups that the command belongs to (comma-separated).
+
+.. code-block:: reStructuredText
+
+    .. argparse::
+       :filename: ../test/sample.py
+       :func: parser
+       :prog: sample
+       :index-groups: Basic Commands
+
+For an HTML build, the index is created with the file name ``commands-by-group.html`` in the output directory.
+You can cross reference the index from other files with the ``:ref:`commands-by-group``` role.
+
+Like the simple index, the ``sphinxarg_commands_by_group_index_in_toctree`` option enables you to reference the index in ``toctree`` directives.
+
+This index has two more options.
+
+.. code-block:: python
+
+    sphinxarg_commands_by_group_index_in_toctree = True
+    sphinxarg_commands_by_group_index_file_suffix = "by-service"
+    sphinxarg_commands_by_group_index_title = "Commands by Service"
+
+
+The ``sphinxarg_commands_by_group_index_file_suffix`` option overrides the default index name of ``commands-by-group.html``.
+The value ``commands-`` is concatenated with the value you specify.
+In the preceding sample, the index file name is created as ``commands-by-service.html``.
+If you specify this option, the default reference of ``:ref:`commands-by-group``` is overridden with the value that you create.
+
+The ``sphinxarg_commands_by_group_index_title`` option overrides the default first-level heading for the file.
+The default heading is "Commands by Group".
+The value you specify replaces the default value.
+
+Customizing the Indices
+-----------------------
+
+By default, indices are created with the ``domainindex.html`` template.
+If you want to customize the appearance of an index, copy the default ``domainindex.html`` file for your theme to the ``_templates`` directory in your project and modify it.
+
+If you want to customize both indices, but one template cannot accommodate both of them, you can create an additional index template, such as ``customindex.html``.
+You can configure Sphinx to use the additional template for an index by modifying the ``conf.py`` for the project like the following example.
+
+.. code-block:: python
+
+   def page_template(app: "Sphinx", pagename, templatename, context, doctree) -> str:
+       if pagename == "commands-by-group":
+           return "customindex.html"
+       else:
+           return templatename
+
+   def setup(app: "Sphinx"):
+       app.connect('html-page-context', page_template)
+
+For more information, refer to the Sphinx documentation for :ref:`sphinx:templating` and the :doc:`sphinx:extdev/appapi`.

pyproject.toml

@@ -36,12 +36,11 @@ classifiers = [
     "Topic :: Documentation :: Sphinx",
 ]
 dependencies = [
-    "sphinx>=5.1.0",
+    "sphinx>=5.1.0,<9.0.0",
     "docutils>=0.19",  # for get_default_settings()
 ]
 dynamic = ["version"]
 
-
 [project.optional-dependencies]
 markdown = [
     "CommonMark>=0.5.6"
@@ -98,6 +97,7 @@ multi_line_output = 3
 [tool.mypy]
 files = ["sphinxarg", "test"]
 python_version = "3.10"
+exclude = '''(?x)( ^test/roots | ^docs )'''
 
 [[tool.mypy.overrides]]
 module = [