Use with Sphinx

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.

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

base:#
type: dict, optional
argument path: base

Base argument with nested structure

sub1:#
type: int
argument path: base/sub1

Sub argument 1

sub2:#
type: dict
argument path: base/sub2

Sub argument 2

subsub1:#
type: int
argument path: base/sub2/subsub1

Sub-sub argument 1

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.

Contents