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.

test_list:

type: typing.List[int], optional

argument path: test/test_list

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.

• 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_list:

type: list

argument path: test[test_variant_argument]/test_repeat_list

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_list/test_repeat_item

This argument/variant is only used to test.

test_repeat_dict:

type: dict

argument path: test[test_variant_argument]/test_repeat_dict

This argument/variant is only used to test.

This argument takes a dict with each key-value pair containing the following:

test_repeat_item:

type: bool

argument path: test[test_variant_argument]/test_repeat_dict/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

To write Markdown files with MyST-Parser, one can use:

```{eval-rst}
.. dargs::
   :module: dargs.sphinx
   :func: _test_argument
```

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.