Skip to content

Commit ed1d36e

Browse files
gaborbernatgaborbernat
authored
📝 docs(readme): restructure with Diataxis sections (#292)
1 parent 56ac49d commit ed1d36e

File tree

1 file changed

+156
-55
lines changed

1 file changed

+156
-55
lines changed

‎README.md‎

Lines changed: 156 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -7,93 +7,194 @@
77
[![PyPI - License](https://img.shields.io/pypi/l/sphinx-argparse-cli?style=flat-square)](https://opensource.org/licenses/MIT)
88
[![check](https://github.com/tox-dev/sphinx-argparse-cli/actions/workflows/check.yaml/badge.svg)](https://github.com/tox-dev/sphinx-argparse-cli/actions/workflows/check.yaml)
99

10-
Render CLI arguments (sub-commands friendly) defined by the argparse module. For live demo checkout the documentation of
11-
[tox](https://tox.wiki/en/latest/cli_interface.html),
12-
[pypa-build](https://pypa-build.readthedocs.io/en/latest/#python-m-build) and
13-
[mdpo](https://mondeja.github.io/mdpo/latest/cli.html).
10+
Render CLI arguments (sub-commands friendly) defined by the argparse module.
1411

15-
## Installation
12+
## Getting started
13+
14+
Install the package:
1615

1716
```bash
1817
python -m pip install sphinx-argparse-cli
1918
```
2019

21-
## Enable in `conf.py`
20+
Add the extension to your `conf.py`:
2221

2322
```python
24-
# just add it to your list of extensions to load within conf.py
2523
extensions = ["sphinx_argparse_cli"]
2624
```
2725

28-
## use
26+
Use the directive in any reStructuredText file:
27+
28+
```rst
29+
.. sphinx_argparse_cli::
30+
:module: my_project.cli
31+
:func: build_parser
32+
```
33+
34+
`:module:` points to the Python module containing the parser, and `:func:` names a zero-argument function that returns
35+
an `ArgumentParser`. Build your docs and the full CLI reference appears automatically.
2936

30-
Within the reStructuredText files use the `sphinx_argparse_cli` directive that takes, at least, two arguments:
37+
## How-to guides
3138

32-
| Name | Description |
33-
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
34-
| module | the module path to where the parser is defined |
35-
| func | the name of the function that once called with no arguments constructs the parser |
36-
| prog | (optional) when provided, overwrites the `<prog>` name. |
37-
| hook | (optional) hook `argparse` to retrieve the parser if `func` uses a parser instead of returning it. |
38-
| title | (optional) when provided, overwrites the `<prog> - CLI interface` title added by default and when empty, will not be included |
39-
| description | (optional) when provided, overwrites the description and when empty, will not be included |
40-
| epilog | (optional) when provided, overwrites the epilog and when empty, will not be included |
41-
| usage_width | (optional) how large should usage examples be - defaults to 100 character |
42-
| usage_first | (optional) show usage before description |
43-
| group_title_prefix | (optional) groups subsections title prefixes, accepts the string `{prog}` as a replacement for the program name - defaults to `{prog}` |
44-
| group_sub_title_prefix | (optional) subcommands groups subsections title prefixes, accepts replacement of `{prog}` and `{subcommand}` for program and subcommand name - defaults to `{prog} {subcommand}` |
45-
| no_default_values | (optional) suppresses generation of `default` entries |
46-
| force_refs_lower | (optional) Sphinx `:ref:` only supports lower-case references. With this, any capital letter in generated reference anchors are lowered and given an `_` prefix (i.e. `A` becomes `_a`) |
39+
### Override the program name
4740

48-
For example:
41+
By default the program name comes from the parser. Use `:prog:` to replace it:
4942

5043
```rst
5144
.. sphinx_argparse_cli::
52-
:module: a_project.cli
45+
:module: my_project.cli
5346
:func: build_parser
54-
:prog: my-cli-program
47+
:prog: my-cli
5548
```
5649

57-
If you have code that creates and uses a parser but does not return it, you can specify the `:hook:` flag:
50+
### Hook into a parser that is not returned
51+
52+
When a function creates and uses a parser internally without returning it, set the `:hook:` flag to intercept
53+
`argparse.ArgumentParser`:
5854

5955
```rst
6056
.. sphinx_argparse_cli::
61-
:module: a_project.cli
57+
:module: my_project.cli
6258
:func: main
6359
:hook:
64-
:prog: my-cli-program
60+
:prog: my-cli
61+
```
62+
63+
### Customize section titles
64+
65+
Control how group and subcommand headings are rendered with `:group_title_prefix:` and `:group_sub_title_prefix:`. Both
66+
accept `{prog}` and the sub-title also accepts `{subcommand}`:
67+
68+
```rst
69+
.. sphinx_argparse_cli::
70+
:module: my_project.cli
71+
:func: build_parser
72+
:group_title_prefix: {prog}
73+
:group_sub_title_prefix: {prog} {subcommand}
6574
```
6675

67-
### Refer to generated content
76+
### Suppress default values
6877

69-
The tool will register reference links to all anchors. This means that you can use the sphinx `ref` role to refer to
70-
both the (sub)command title/groups and every flag/argument. The tool offers a configuration flag
71-
`sphinx_argparse_cli_prefix_document` (change by setting this variable in `conf.py` - by default `False`). This option
72-
influences the reference ids generated. If it's false the reference will be the anchor id (the text appearing after the
73-
`'#` in the URI once you click on it). If it's true the anchor id will be prefixed by the document name (this is useful
74-
to avoid reference label clash when the same anchors are generated in multiple documents).
78+
Hide `(default: ...)` annotations from the output:
7579

76-
For example in case of a `tox` command, and `sphinx_argparse_cli_prefix_document=False` (default):
80+
```rst
81+
.. sphinx_argparse_cli::
82+
:module: my_project.cli
83+
:func: build_parser
84+
:no_default_values:
85+
```
7786

78-
- to refer to the optional arguments group use ``:ref:`tox-optional-arguments` ``,
79-
- to refer to the run subcommand use ``:ref:`tox-run` ``,
80-
- to refer to flag `--magic` of the `run` sub-command use ``:ref:`tox-run---magic` ``.
87+
### Control usage display
8188

82-
For example in case of a `tox` command, and `sphinx_argparse_cli_prefix_document=True`, and the current document name
83-
being `cli`:
89+
Set the character width for usage lines and optionally show usage before the description:
8490

85-
- to refer to the optional arguments group use ``:ref:`cli:tox-optional-arguments` ``,
86-
- to refer to the run subcommand use ``:ref:`cli:tox-run` ``,
87-
- to refer to flag `--magic` of the `run` sub-command use ``:ref:`cli:tox-run---magic` ``.
91+
```rst
92+
.. sphinx_argparse_cli::
93+
:module: my_project.cli
94+
:func: build_parser
95+
:usage_width: 80
96+
:usage_first:
97+
```
98+
99+
### Override title, description, or epilog
100+
101+
Replace auto-detected values, or pass an empty string to suppress them entirely:
102+
103+
```rst
104+
.. sphinx_argparse_cli::
105+
:module: my_project.cli
106+
:func: build_parser
107+
:title: Custom Title
108+
:description: Custom description text.
109+
:epilog:
110+
```
88111

89-
Due to Sphinx's `:ref:` only supporting lower-case values, if you need to distinguish mixed case program names or
90-
arguments, set the `:force_refs_lower:` argument. With this flag, captial-letters in references will be converted to
91-
their lower-case counterpart and prefixed with an `_`. For example:
112+
### Cross-reference generated anchors
92113

93-
- A `prog` name `SampleProgram` will be referenced as ``:ref:`_sample_program...` ``.
94-
- To distinguish between mixed case flags `-a` and `-A` use ``:ref:`_sample_program--a` `` and
95-
``:ref:`_sample_program--_a` `` respectively
114+
The directive registers Sphinx reference labels for every command, group, and flag. Use the `:ref:` role to link to
115+
them.
116+
117+
With `sphinx_argparse_cli_prefix_document = False` (default):
118+
119+
```rst
120+
:ref:`tox-optional-arguments`
121+
:ref:`tox-run`
122+
:ref:`tox-run---magic`
123+
```
124+
125+
With `sphinx_argparse_cli_prefix_document = True` (anchors prefixed by document name, avoids clashes across documents):
126+
127+
```rst
128+
:ref:`cli:tox-optional-arguments`
129+
:ref:`cli:tox-run`
130+
:ref:`cli:tox-run---magic`
131+
```
132+
133+
The anchor text is visible after the `#` in the URL when you click a heading.
134+
135+
### Handle mixed-case references
136+
137+
Sphinx `:ref:` only supports lower-case targets. When your program name or flags contain capital letters, set
138+
`:force_refs_lower:` to convert them — each upper-case letter becomes its lower-case form prefixed with `_` (e.g. `A`
139+
becomes `_a`):
140+
141+
```rst
142+
.. sphinx_argparse_cli::
143+
:module: my_project.cli
144+
:func: build_parser
145+
:force_refs_lower:
146+
```
147+
148+
For a program named `SampleProgram`:
149+
150+
```rst
151+
:ref:`_sample_program--a` .. flag -a
152+
:ref:`_sample_program--_a` .. flag -A
153+
```
154+
155+
If you do not need Sphinx `:ref:` cross-references you can leave this off to keep mixed-case anchors in the HTML output,
156+
but enabling it later will change existing anchor URLs.
157+
158+
### Add extra content after generated docs
159+
160+
Any content nested inside the directive is appended after the generated CLI documentation:
161+
162+
```rst
163+
.. sphinx_argparse_cli::
164+
:module: my_project.cli
165+
:func: build_parser
166+
167+
Extra notes or examples rendered after the CLI reference.
168+
```
96169

97-
Note that if you are _not_ concerned about using internal Sphinx `:ref:` cross-references, you may choose to leave this
98-
off to maintain mixed-case anchors in your output HTML; but be aware that later enabling it will change your anchors in
99-
the output HTML.
170+
## Reference
171+
172+
### Directive options
173+
174+
| Option | Type | Default | Description |
175+
| -------------------------- | ------ | ------------------------ | ------------------------------------------------------------------------------ |
176+
| `:module:` | string | **required** | Python module path where the parser is defined |
177+
| `:func:` | string | **required** | Zero-argument function that returns an `ArgumentParser` |
178+
| `:prog:` | string | parser's `prog` | Override the displayed program name |
179+
| `:hook:` | flag | off | Intercept `ArgumentParser` instead of expecting `func` to return it |
180+
| `:title:` | string | `<prog> - CLI interface` | Custom title; empty string suppresses it |
181+
| `:description:` | string | parser's description | Custom description; empty string suppresses it |
182+
| `:epilog:` | string | parser's epilog | Custom epilog; empty string suppresses it |
183+
| `:usage_width:` | int | `100` | Character width for usage lines |
184+
| `:usage_first:` | flag | off | Show usage before the description |
185+
| `:group_title_prefix:` | string | `{prog}` | Heading prefix for groups; `{prog}` is replaced with the program name |
186+
| `:group_sub_title_prefix:` | string | `{prog} {subcommand}` | Heading prefix for subcommand groups; supports `{prog}` and `{subcommand}` |
187+
| `:no_default_values:` | flag | off | Suppress `(default: ...)` annotations |
188+
| `:force_refs_lower:` | flag | off | Lower-case reference anchors with `_` prefix for capitals (for `:ref:` compat) |
189+
190+
### Configuration values (`conf.py`)
191+
192+
| Name | Type | Default | Description |
193+
| ------------------------------------- | ---- | ------- | ---------------------------------------------------------------- |
194+
| `sphinx_argparse_cli_prefix_document` | bool | `False` | Prefix reference anchors with the document name to avoid clashes |
195+
196+
## Live examples
197+
198+
- [tox](https://tox.wiki/en/latest/cli_interface.html)
199+
- [pypa-build](https://pypa-build.readthedocs.io/en/latest/#python-m-build)
200+
- [mdpo](https://mondeja.github.io/mdpo/latest/cli.html)

0 commit comments

Comments
 (0)