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.

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.