===========
Basic usage
===========

This extension adds the "argparse" directive:

.. code:: rst

   .. argparse::
      :module: my.module
      :func: my_func_that_returns_a_parser
      :prog: fancytool

The ``module``, ``func`` and ``prog`` options are required.

``func`` is a function that returns an instance of the :py:class:`argparse.ArgumentParser` class.

Alternatively, one can use :ref: like this:

.. code:: rst

   .. argparse::
      :ref: my.module.my_func_that_returns_a_parser
      :prog: fancytool

In this case :ref: points directly to argument parser instance.

For this directive to work, you should point it to the function that will return a pre-filled ``ArgumentParser``.
Something like:

.. code:: python

   def my_func_that_return_parser():
       parser = argparse.ArgumentParser()
       parser.add_argument('foo', default=False, help='foo help')
       parser.add_argument('bar', default=False)

       subparsers = parser.add_subparsers()

       subparser = subparsers.add_parser('install', help='install help')
       subparser.add_argument('ref', type=str, help='foo1 help')
       subparser.add_argument('--upgrade', action='store_true', default=False, help='foo2 help')

       return parser

.. note::
    We will use this example as a reference for every example in this document.

To document a file that is not part of a module, use :filename:

.. code:: rst

   .. argparse::
      :filename: script.py
      :func: my_func_that_returns_a_parser
      :prog: script.py

The 'filename' option can be an absolute path or a relative one.
When a relative path is provided, the Sphinx ``srcdir`` will be taken as the base, which is the directory housing the active ``conf.py`` file.

\:module\:
    Module name, where the function is located

\:func\:
    Function name

\:ref\:
    A combination of :module: and :func:

\:filename\:
    A file name, in cases where the file to be documented is not part of a module.

\:prog\:
    The name of your tool (or how it should appear in the documentation). For example, if you run your script as
    ``./boo --some args`` then \:prog\: will be "boo"

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

   .. argparse::
      :module: my.module
      :func: my_func_that_return_parser
      :prog: fancytool
      :path: install

This will render same doc for "install" subcommand.

Nesting level is unlimited:

.. code:: rst

   .. argparse::
      :module: my.module
      :func: my_func_that_return_parser
      :prog: fancytool
      :path: install subcomand1 subcommand2 subcommand3


Other useful directives
=======================

:nodefault: Do not show any default values.

:nodefaultconst: Like nodefault:, except it applies only to arguments of types ``store_const``, ``store_true`` and ``store_false``.

:nosubcommands: Do not show subcommands.

:noepilog: Do not parse the epilogue, which can be useful if it contains text that could be incorrectly parse as reStructuredText.

: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`.