Use with Sphinx

Add dargs.sphinx to the extensions of conf.py:

extensions = [
    'dargs.sphinx',
]

Then dargs directive will be enabled:

.. dargs::
   :module: dargs.sphinx
   :func: _test_argument

where _test_argument returns an Argument. The documentation will be rendered as:

test:
type: str | dict
argument path: test

This argument/variant is only used to test.

test_argument:
type: str
argument path: test/test_argument

This argument/variant is only used to test.

Depending on the value of test_variant, different sub args are accepted.

test_variant:
type: str (flag key)
argument path: test/test_variant
possible choices: test_variant_argument

This argument/variant is only used to test.

When test_variant is set to test_variant_argument:

This argument/variant is only used to test.

test_repeat:
type: list
argument path: test[test_variant_argument]/test_repeat

This argument/variant is only used to test.

This argument takes a list with each element containing the following:

test_repeat_item:
type: bool
argument path: test[test_variant_argument]/test_repeat/test_repeat_item

This argument/variant is only used to test.

A list of Argument is also accepted.

test1:
type: int
argument path: test1

Argument 1

test2:
type: NoneType | float
argument path: test2

Argument 2

test3:
type: typing.List[str], optional, default: ['test']
argument path: test3

Argument 3

Cross-referencing Arguments

Both the following ways will create a cross-reference to the argument:

Both :dargs:argument:`this <test/test_argument>` and :ref:`this <test/test_argument>` will create a cross-reference to the argument!

It will be rendered as:

Both this and this will create a cross-reference to the argument!

Index page

The arguments will be added into the Index page. See test_argument in the Index page.