Moved sphinxarg options from nested dict to direct options + Added full list to docs

Author: RobertoRoos

docs/changelog.rst

@@ -48,7 +48,7 @@ The following enhancements to the HTML output are described on the [Usage](https
 
 * Optional command index.
 * Optional ``:index-groups:`` field to the directive for an command-by-group index.
-* A ``full_subcommand_name`` option to print fully-qualified sub-command headings.
+* 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.

docs/usage.rst

@@ -76,8 +76,29 @@ 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
 ==================
 
@@ -134,9 +155,7 @@ the option in the ``conf.py`` for your project:
 
 .. code-block:: python
 
-   sphinx_argparse_conf = {
-     "full_subcommand_name": True,
-   }
+   sphinxarg_full_subcommand_name = True
 
 
 Indices
@@ -154,10 +173,8 @@ To enable the simple command index, add the following to the project ``conf.py``
 
 .. code-block:: python
 
-    sphinx_argparse_conf = {
-      "build_commands_index": True,
-      "commands_index_in_toctree": True,
-    }
+    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.
@@ -176,10 +193,8 @@ To enable the more complex index, add the following to the project ``conf.py`` f
 
 .. code-block:: python
 
-    sphinx_argparse_conf = {
-      "build_commands_by_group_index": True,
-      "commands_by_group_index_in_toctree": True,
-    }
+    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).
@@ -195,24 +210,23 @@ Specify one or more groups that the command belongs to (comma-separated).
 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 ``commands_by_group_index_in_toctree`` option enables you to reference the index in ``toctree`` directives.
+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
 
-    sphinx_argparse_conf = {
-      "commands_by_group_index_in_toctree": True,
-      "commands_by_group_index_file_suffix": "by-service",
-      "commands_by_group_index_title": "Commands by Service",
-    }
+    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 ``commands_by_group_index_file_suffix`` option overrides the default index name of ``commands-by-group.html``.
+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 ``commands_by_group_index_title`` option overides the default first-level heading for the file.
+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.
 

sphinxarg/ext.py

@@ -524,9 +524,7 @@ def _print_subcommands(self, data, nested_content, markdown_help=False, settings
 
         definitions = map_nested_definitions(nested_content)
         items = []
-        full_subcommand_name_true = (
-                ('full_subcommand_name', True) in self.config.sphinx_argparse_conf.items()
-        )
+        full_subcommand_name_true = self.config.sphinxarg_full_subcommand_name
         domain = cast(ArgParseDomain, self.env.domains[ArgParseDomain.name])
 
         if 'children' in data:
@@ -859,6 +857,7 @@ def generate(
 
 
 class CommandsByGroupIndex(Index):
+    # Defaults (can be overridden through `conf.py`):
     name = 'by-group'
     localname = 'Commands by Group'
 
@@ -977,28 +976,27 @@ def _create_temporary_dummy_file(
 
 
 def configure_ext(app: Sphinx) -> None:
-    conf = app.config.sphinx_argparse_conf
     domain = cast(ArgParseDomain, app.env.domains[ArgParseDomain.name])
     build_index = False
     build_by_group_index = False
-    if 'commands_by_group_index_file_suffix' in conf:
-        build_by_group_index = True
-        CommandsByGroupIndex.name = conf.get('commands_by_group_index_file_suffix')
-    if 'commands_by_group_index_title' in conf:
-        build_by_group_index = True
-        CommandsByGroupIndex.localname = conf.get('commands_by_group_index_title')
-    if ('commands_index_in_toctree', True) in conf.items():
+
+    CommandsByGroupIndex.name = app.config.sphinxarg_commands_by_group_index_file_suffix
+    CommandsByGroupIndex.localname = app.config.sphinxarg_commands_by_group_index_title
+
+    if app.config.sphinxarg_commands_index_in_toctree:
         build_index = True
         docname = f'{ArgParseDomain.name}-{CommandsIndex.name}.rst'
         _create_temporary_dummy_file(app, domain, docname, CommandsIndex.localname)
-    if ('commands_by_group_index_in_toctree', True) in conf.items():
+
+    if app.config.sphinxarg_commands_by_group_index_in_toctree:
         build_by_group_index = True
         docname = f'{ArgParseDomain.name}-{CommandsByGroupIndex.name}.rst'
         _create_temporary_dummy_file(app, domain, docname, CommandsByGroupIndex.localname)
 
-    if build_index or ('build_commands_index', True) in conf.items():
+    if build_index or app.config.sphinxarg_build_commands_index:
         domain.indices.append(CommandsIndex)
-    if build_by_group_index or ('build_commands_by_group_index', True) in conf.items():
+
+    if build_by_group_index or app.config.sphinxarg_build_commands_by_group_index:
         domain.indices.append(CommandsByGroupIndex)
 
     # Call setup so that :ref:`commands-...` are link targets.
@@ -1009,7 +1007,18 @@ def setup(app: Sphinx):
     app.setup_extension('sphinx.ext.autodoc')
     app.add_domain(ArgParseDomain)
     app.add_directive('argparse', ArgParseDirective)
-    app.add_config_value('sphinx_argparse_conf', {}, 'html', types={dict})
+
+    # Config options must be mentioned in ``usage.rst`` too!
+
+    app.add_config_value('sphinxarg_full_subcommand_name', False, 'html', bool)
+    app.add_config_value('sphinxarg_build_commands_index', False, 'html', bool)
+    app.add_config_value('sphinxarg_commands_index_in_toctree', False, 'html', bool)
+
+    app.add_config_value('sphinxarg_build_commands_by_group_index', False, 'html', bool)
+    app.add_config_value('sphinxarg_commands_by_group_index_in_toctree', False, 'html', bool)
+    app.add_config_value('sphinxarg_commands_by_group_index_file_suffix', CommandsByGroupIndex.name, 'html', str)
+    app.add_config_value('sphinxarg_commands_by_group_index_title', CommandsByGroupIndex.localname, 'html', str)
+
     app.connect('builder-inited', configure_ext)
     app.connect('build-finished', _delete_temporary_files)
     return {