sphinx-argparse-cli 1.21.0__tar.gz → 1.21.2__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- sphinx_argparse_cli-1.21.2/PKG-INFO +231 -0
- sphinx_argparse_cli-1.21.2/README.md +200 -0
- {sphinx_argparse_cli-1.21.0 → sphinx_argparse_cli-1.21.2}/src/sphinx_argparse_cli/_logic.py +2 -1
- {sphinx_argparse_cli-1.21.0 → sphinx_argparse_cli-1.21.2}/src/sphinx_argparse_cli/version.py +2 -2
- {sphinx_argparse_cli-1.21.0 → sphinx_argparse_cli-1.21.2}/tests/test_logic.py +7 -3
- sphinx_argparse_cli-1.21.0/PKG-INFO +0 -130
- sphinx_argparse_cli-1.21.0/README.md +0 -99
- {sphinx_argparse_cli-1.21.0 → sphinx_argparse_cli-1.21.2}/.gitignore +0 -0
- {sphinx_argparse_cli-1.21.0 → sphinx_argparse_cli-1.21.2}/LICENSE.txt +0 -0
- {sphinx_argparse_cli-1.21.0 → sphinx_argparse_cli-1.21.2}/pyproject.toml +0 -0
- {sphinx_argparse_cli-1.21.0 → sphinx_argparse_cli-1.21.2}/src/sphinx_argparse_cli/__init__.py +0 -0
- {sphinx_argparse_cli-1.21.0 → sphinx_argparse_cli-1.21.2}/src/sphinx_argparse_cli/py.typed +0 -0
- {sphinx_argparse_cli-1.21.0 → sphinx_argparse_cli-1.21.2}/tests/complex.txt +0 -0
- {sphinx_argparse_cli-1.21.0 → sphinx_argparse_cli-1.21.2}/tests/complex_pre_310.txt +0 -0
- {sphinx_argparse_cli-1.21.0 → sphinx_argparse_cli-1.21.2}/tests/conftest.py +0 -0
- {sphinx_argparse_cli-1.21.0 → sphinx_argparse_cli-1.21.2}/tests/test_sphinx_argparse_cli.py +0 -0
|
@@ -0,0 +1,231 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: sphinx-argparse-cli
|
|
3
|
+
Version: 1.21.2
|
|
4
|
+
Summary: render CLI arguments (sub-commands friendly) defined by argparse module
|
|
5
|
+
Project-URL: Documentation, https://github.com/tox-dev/sphinx-argparse-cli#sphinx-argparse-cli
|
|
6
|
+
Project-URL: Homepage, https://github.com/tox-dev/sphinx-argparse-cli
|
|
7
|
+
Project-URL: Source, https://github.com/tox-dev/sphinx-argparse-cli
|
|
8
|
+
Project-URL: Tracker, https://github.com/tox-dev/sphinx-argparse-cli/issues
|
|
9
|
+
Maintainer-email: Bernat Gabor <gaborjbernat@gmail.com>
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE.txt
|
|
12
|
+
Keywords: argparse,sphinx
|
|
13
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
14
|
+
Classifier: Environment :: Console
|
|
15
|
+
Classifier: Framework :: Sphinx
|
|
16
|
+
Classifier: Framework :: Sphinx :: Extension
|
|
17
|
+
Classifier: Intended Audience :: Developers
|
|
18
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
19
|
+
Classifier: Operating System :: OS Independent
|
|
20
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
24
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
25
|
+
Classifier: Programming Language :: Python :: Implementation :: CPython
|
|
26
|
+
Classifier: Topic :: Documentation
|
|
27
|
+
Classifier: Topic :: Documentation :: Sphinx
|
|
28
|
+
Requires-Python: >=3.11
|
|
29
|
+
Requires-Dist: sphinx>=9.0.4
|
|
30
|
+
Description-Content-Type: text/markdown
|
|
31
|
+
|
|
32
|
+
# sphinx-argparse-cli
|
|
33
|
+
|
|
34
|
+
[](https://pypi.org/project/sphinx-argparse-cli)
|
|
35
|
+
[](https://pypi.org/project/sphinx-argparse-cli)
|
|
36
|
+
[](https://pypi.org/project/sphinx-argparse-cli)
|
|
37
|
+
[](https://pepy.tech/project/sphinx-argparse-cli)
|
|
38
|
+
[](https://opensource.org/licenses/MIT)
|
|
39
|
+
[](https://github.com/tox-dev/sphinx-argparse-cli/actions/workflows/check.yaml)
|
|
40
|
+
|
|
41
|
+
Render CLI arguments (sub-commands friendly) defined by the argparse module.
|
|
42
|
+
|
|
43
|
+
## Getting started
|
|
44
|
+
|
|
45
|
+
Install the package:
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
python -m pip install sphinx-argparse-cli
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Add the extension to your `conf.py`:
|
|
52
|
+
|
|
53
|
+
```python
|
|
54
|
+
extensions = ["sphinx_argparse_cli"]
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Use the directive in any reStructuredText file:
|
|
58
|
+
|
|
59
|
+
```rst
|
|
60
|
+
.. sphinx_argparse_cli::
|
|
61
|
+
:module: my_project.cli
|
|
62
|
+
:func: build_parser
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
`:module:` points to the Python module containing the parser, and `:func:` names a zero-argument function that returns
|
|
66
|
+
an `ArgumentParser`. Build your docs and the full CLI reference appears automatically.
|
|
67
|
+
|
|
68
|
+
## How-to guides
|
|
69
|
+
|
|
70
|
+
### Override the program name
|
|
71
|
+
|
|
72
|
+
By default the program name comes from the parser. Use `:prog:` to replace it:
|
|
73
|
+
|
|
74
|
+
```rst
|
|
75
|
+
.. sphinx_argparse_cli::
|
|
76
|
+
:module: my_project.cli
|
|
77
|
+
:func: build_parser
|
|
78
|
+
:prog: my-cli
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### Hook into a parser that is not returned
|
|
82
|
+
|
|
83
|
+
When a function creates and uses a parser internally without returning it, set the `:hook:` flag to intercept
|
|
84
|
+
`argparse.ArgumentParser`:
|
|
85
|
+
|
|
86
|
+
```rst
|
|
87
|
+
.. sphinx_argparse_cli::
|
|
88
|
+
:module: my_project.cli
|
|
89
|
+
:func: main
|
|
90
|
+
:hook:
|
|
91
|
+
:prog: my-cli
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
### Customize section titles
|
|
95
|
+
|
|
96
|
+
Control how group and subcommand headings are rendered with `:group_title_prefix:` and `:group_sub_title_prefix:`. Both
|
|
97
|
+
accept `{prog}` and the sub-title also accepts `{subcommand}`:
|
|
98
|
+
|
|
99
|
+
```rst
|
|
100
|
+
.. sphinx_argparse_cli::
|
|
101
|
+
:module: my_project.cli
|
|
102
|
+
:func: build_parser
|
|
103
|
+
:group_title_prefix: {prog}
|
|
104
|
+
:group_sub_title_prefix: {prog} {subcommand}
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
### Suppress default values
|
|
108
|
+
|
|
109
|
+
Hide `(default: ...)` annotations from the output:
|
|
110
|
+
|
|
111
|
+
```rst
|
|
112
|
+
.. sphinx_argparse_cli::
|
|
113
|
+
:module: my_project.cli
|
|
114
|
+
:func: build_parser
|
|
115
|
+
:no_default_values:
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
### Control usage display
|
|
119
|
+
|
|
120
|
+
Set the character width for usage lines and optionally show usage before the description:
|
|
121
|
+
|
|
122
|
+
```rst
|
|
123
|
+
.. sphinx_argparse_cli::
|
|
124
|
+
:module: my_project.cli
|
|
125
|
+
:func: build_parser
|
|
126
|
+
:usage_width: 80
|
|
127
|
+
:usage_first:
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
### Override title, description, or epilog
|
|
131
|
+
|
|
132
|
+
Replace auto-detected values, or pass an empty string to suppress them entirely:
|
|
133
|
+
|
|
134
|
+
```rst
|
|
135
|
+
.. sphinx_argparse_cli::
|
|
136
|
+
:module: my_project.cli
|
|
137
|
+
:func: build_parser
|
|
138
|
+
:title: Custom Title
|
|
139
|
+
:description: Custom description text.
|
|
140
|
+
:epilog:
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
### Cross-reference generated anchors
|
|
144
|
+
|
|
145
|
+
The directive registers Sphinx reference labels for every command, group, and flag. Use the `:ref:` role to link to
|
|
146
|
+
them.
|
|
147
|
+
|
|
148
|
+
With `sphinx_argparse_cli_prefix_document = False` (default):
|
|
149
|
+
|
|
150
|
+
```rst
|
|
151
|
+
:ref:`tox-optional-arguments`
|
|
152
|
+
:ref:`tox-run`
|
|
153
|
+
:ref:`tox-run---magic`
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
With `sphinx_argparse_cli_prefix_document = True` (anchors prefixed by document name, avoids clashes across documents):
|
|
157
|
+
|
|
158
|
+
```rst
|
|
159
|
+
:ref:`cli:tox-optional-arguments`
|
|
160
|
+
:ref:`cli:tox-run`
|
|
161
|
+
:ref:`cli:tox-run---magic`
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
The anchor text is visible after the `#` in the URL when you click a heading.
|
|
165
|
+
|
|
166
|
+
### Handle mixed-case references
|
|
167
|
+
|
|
168
|
+
Sphinx `:ref:` only supports lower-case targets. When your program name or flags contain capital letters, set
|
|
169
|
+
`:force_refs_lower:` to convert them — each upper-case letter becomes its lower-case form prefixed with `_` (e.g. `A`
|
|
170
|
+
becomes `_a`):
|
|
171
|
+
|
|
172
|
+
```rst
|
|
173
|
+
.. sphinx_argparse_cli::
|
|
174
|
+
:module: my_project.cli
|
|
175
|
+
:func: build_parser
|
|
176
|
+
:force_refs_lower:
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
For a program named `SampleProgram`:
|
|
180
|
+
|
|
181
|
+
```rst
|
|
182
|
+
:ref:`_sample_program--a` .. flag -a
|
|
183
|
+
:ref:`_sample_program--_a` .. flag -A
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
If you do not need Sphinx `:ref:` cross-references you can leave this off to keep mixed-case anchors in the HTML output,
|
|
187
|
+
but enabling it later will change existing anchor URLs.
|
|
188
|
+
|
|
189
|
+
### Add extra content after generated docs
|
|
190
|
+
|
|
191
|
+
Any content nested inside the directive is appended after the generated CLI documentation:
|
|
192
|
+
|
|
193
|
+
```rst
|
|
194
|
+
.. sphinx_argparse_cli::
|
|
195
|
+
:module: my_project.cli
|
|
196
|
+
:func: build_parser
|
|
197
|
+
|
|
198
|
+
Extra notes or examples rendered after the CLI reference.
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
## Reference
|
|
202
|
+
|
|
203
|
+
### Directive options
|
|
204
|
+
|
|
205
|
+
| Option | Type | Default | Description |
|
|
206
|
+
| -------------------------- | ------ | ------------------------ | ------------------------------------------------------------------------------ |
|
|
207
|
+
| `:module:` | string | **required** | Python module path where the parser is defined |
|
|
208
|
+
| `:func:` | string | **required** | Zero-argument function that returns an `ArgumentParser` |
|
|
209
|
+
| `:prog:` | string | parser's `prog` | Override the displayed program name |
|
|
210
|
+
| `:hook:` | flag | off | Intercept `ArgumentParser` instead of expecting `func` to return it |
|
|
211
|
+
| `:title:` | string | `<prog> - CLI interface` | Custom title; empty string suppresses it |
|
|
212
|
+
| `:description:` | string | parser's description | Custom description; empty string suppresses it |
|
|
213
|
+
| `:epilog:` | string | parser's epilog | Custom epilog; empty string suppresses it |
|
|
214
|
+
| `:usage_width:` | int | `100` | Character width for usage lines |
|
|
215
|
+
| `:usage_first:` | flag | off | Show usage before the description |
|
|
216
|
+
| `:group_title_prefix:` | string | `{prog}` | Heading prefix for groups; `{prog}` is replaced with the program name |
|
|
217
|
+
| `:group_sub_title_prefix:` | string | `{prog} {subcommand}` | Heading prefix for subcommand groups; supports `{prog}` and `{subcommand}` |
|
|
218
|
+
| `:no_default_values:` | flag | off | Suppress `(default: ...)` annotations |
|
|
219
|
+
| `:force_refs_lower:` | flag | off | Lower-case reference anchors with `_` prefix for capitals (for `:ref:` compat) |
|
|
220
|
+
|
|
221
|
+
### Configuration values (`conf.py`)
|
|
222
|
+
|
|
223
|
+
| Name | Type | Default | Description |
|
|
224
|
+
| ------------------------------------- | ---- | ------- | ---------------------------------------------------------------- |
|
|
225
|
+
| `sphinx_argparse_cli_prefix_document` | bool | `False` | Prefix reference anchors with the document name to avoid clashes |
|
|
226
|
+
|
|
227
|
+
## Live examples
|
|
228
|
+
|
|
229
|
+
- [tox](https://tox.wiki/en/latest/cli_interface.html)
|
|
230
|
+
- [pypa-build](https://pypa-build.readthedocs.io/en/latest/#python-m-build)
|
|
231
|
+
- [mdpo](https://mondeja.github.io/mdpo/latest/cli.html)
|
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
# sphinx-argparse-cli
|
|
2
|
+
|
|
3
|
+
[](https://pypi.org/project/sphinx-argparse-cli)
|
|
4
|
+
[](https://pypi.org/project/sphinx-argparse-cli)
|
|
5
|
+
[](https://pypi.org/project/sphinx-argparse-cli)
|
|
6
|
+
[](https://pepy.tech/project/sphinx-argparse-cli)
|
|
7
|
+
[](https://opensource.org/licenses/MIT)
|
|
8
|
+
[](https://github.com/tox-dev/sphinx-argparse-cli/actions/workflows/check.yaml)
|
|
9
|
+
|
|
10
|
+
Render CLI arguments (sub-commands friendly) defined by the argparse module.
|
|
11
|
+
|
|
12
|
+
## Getting started
|
|
13
|
+
|
|
14
|
+
Install the package:
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
python -m pip install sphinx-argparse-cli
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Add the extension to your `conf.py`:
|
|
21
|
+
|
|
22
|
+
```python
|
|
23
|
+
extensions = ["sphinx_argparse_cli"]
|
|
24
|
+
```
|
|
25
|
+
|
|
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.
|
|
36
|
+
|
|
37
|
+
## How-to guides
|
|
38
|
+
|
|
39
|
+
### Override the program name
|
|
40
|
+
|
|
41
|
+
By default the program name comes from the parser. Use `:prog:` to replace it:
|
|
42
|
+
|
|
43
|
+
```rst
|
|
44
|
+
.. sphinx_argparse_cli::
|
|
45
|
+
:module: my_project.cli
|
|
46
|
+
:func: build_parser
|
|
47
|
+
:prog: my-cli
|
|
48
|
+
```
|
|
49
|
+
|
|
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`:
|
|
54
|
+
|
|
55
|
+
```rst
|
|
56
|
+
.. sphinx_argparse_cli::
|
|
57
|
+
:module: my_project.cli
|
|
58
|
+
:func: main
|
|
59
|
+
:hook:
|
|
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}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
### Suppress default values
|
|
77
|
+
|
|
78
|
+
Hide `(default: ...)` annotations from the output:
|
|
79
|
+
|
|
80
|
+
```rst
|
|
81
|
+
.. sphinx_argparse_cli::
|
|
82
|
+
:module: my_project.cli
|
|
83
|
+
:func: build_parser
|
|
84
|
+
:no_default_values:
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
### Control usage display
|
|
88
|
+
|
|
89
|
+
Set the character width for usage lines and optionally show usage before the description:
|
|
90
|
+
|
|
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
|
+
```
|
|
111
|
+
|
|
112
|
+
### Cross-reference generated anchors
|
|
113
|
+
|
|
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
|
+
```
|
|
169
|
+
|
|
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)
|
|
@@ -25,6 +25,7 @@ from docutils.nodes import (
|
|
|
25
25
|
Node,
|
|
26
26
|
Text,
|
|
27
27
|
bullet_list,
|
|
28
|
+
container,
|
|
28
29
|
fully_normalize_name,
|
|
29
30
|
list_item,
|
|
30
31
|
literal,
|
|
@@ -187,7 +188,7 @@ class SphinxArgparseCli(SphinxDirective):
|
|
|
187
188
|
self.env.note_reread() # this document needs to be always updated
|
|
188
189
|
title_text = self.options.get("title", f"{self.parser.prog} - CLI interface").strip()
|
|
189
190
|
if not title_text:
|
|
190
|
-
home_section: Element =
|
|
191
|
+
home_section: Element = container("")
|
|
191
192
|
else:
|
|
192
193
|
home_section = section("", title("", Text(title_text)), ids=[self.make_id(title_text)], names=[title_text])
|
|
193
194
|
|
{sphinx_argparse_cli-1.21.0 → sphinx_argparse_cli-1.21.2}/src/sphinx_argparse_cli/version.py
RENAMED
|
@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
|
|
|
28
28
|
commit_id: COMMIT_ID
|
|
29
29
|
__commit_id__: COMMIT_ID
|
|
30
30
|
|
|
31
|
-
__version__ = version = '1.21.
|
|
32
|
-
__version_tuple__ = version_tuple = (1, 21,
|
|
31
|
+
__version__ = version = '1.21.2'
|
|
32
|
+
__version_tuple__ = version_tuple = (1, 21, 2)
|
|
33
33
|
|
|
34
34
|
__commit_id__ = commit_id = None
|
|
@@ -407,6 +407,10 @@ def test_multiword_prog(build_outcome: str) -> None:
|
|
|
407
407
|
|
|
408
408
|
|
|
409
409
|
@pytest.mark.sphinx(buildername="html", testroot="title-empty-groups")
|
|
410
|
-
def test_empty_title_groups_in_toctree(
|
|
411
|
-
|
|
412
|
-
|
|
410
|
+
def test_empty_title_groups_in_toctree(app: SphinxTestApp, monkeypatch: pytest.MonkeyPatch) -> None:
|
|
411
|
+
monkeypatch.setenv("FORCE_COLOR", "1")
|
|
412
|
+
monkeypatch.delenv("NO_COLOR", raising=False)
|
|
413
|
+
app.build()
|
|
414
|
+
cli_html = (Path(app.outdir) / "cli.html").read_text()
|
|
415
|
+
assert '<section id="tool-options">' in cli_html
|
|
416
|
+
assert "be verbose" in cli_html
|
|
@@ -1,130 +0,0 @@
|
|
|
1
|
-
Metadata-Version: 2.4
|
|
2
|
-
Name: sphinx-argparse-cli
|
|
3
|
-
Version: 1.21.0
|
|
4
|
-
Summary: render CLI arguments (sub-commands friendly) defined by argparse module
|
|
5
|
-
Project-URL: Documentation, https://github.com/tox-dev/sphinx-argparse-cli#sphinx-argparse-cli
|
|
6
|
-
Project-URL: Homepage, https://github.com/tox-dev/sphinx-argparse-cli
|
|
7
|
-
Project-URL: Source, https://github.com/tox-dev/sphinx-argparse-cli
|
|
8
|
-
Project-URL: Tracker, https://github.com/tox-dev/sphinx-argparse-cli/issues
|
|
9
|
-
Maintainer-email: Bernat Gabor <gaborjbernat@gmail.com>
|
|
10
|
-
License-Expression: MIT
|
|
11
|
-
License-File: LICENSE.txt
|
|
12
|
-
Keywords: argparse,sphinx
|
|
13
|
-
Classifier: Development Status :: 5 - Production/Stable
|
|
14
|
-
Classifier: Environment :: Console
|
|
15
|
-
Classifier: Framework :: Sphinx
|
|
16
|
-
Classifier: Framework :: Sphinx :: Extension
|
|
17
|
-
Classifier: Intended Audience :: Developers
|
|
18
|
-
Classifier: License :: OSI Approved :: MIT License
|
|
19
|
-
Classifier: Operating System :: OS Independent
|
|
20
|
-
Classifier: Programming Language :: Python :: 3 :: Only
|
|
21
|
-
Classifier: Programming Language :: Python :: 3.11
|
|
22
|
-
Classifier: Programming Language :: Python :: 3.12
|
|
23
|
-
Classifier: Programming Language :: Python :: 3.13
|
|
24
|
-
Classifier: Programming Language :: Python :: 3.14
|
|
25
|
-
Classifier: Programming Language :: Python :: Implementation :: CPython
|
|
26
|
-
Classifier: Topic :: Documentation
|
|
27
|
-
Classifier: Topic :: Documentation :: Sphinx
|
|
28
|
-
Requires-Python: >=3.11
|
|
29
|
-
Requires-Dist: sphinx>=9.0.4
|
|
30
|
-
Description-Content-Type: text/markdown
|
|
31
|
-
|
|
32
|
-
# sphinx-argparse-cli
|
|
33
|
-
|
|
34
|
-
[](https://pypi.org/project/sphinx-argparse-cli)
|
|
35
|
-
[](https://pypi.org/project/sphinx-argparse-cli)
|
|
36
|
-
[](https://pypi.org/project/sphinx-argparse-cli)
|
|
37
|
-
[](https://pepy.tech/project/sphinx-argparse-cli)
|
|
38
|
-
[](https://opensource.org/licenses/MIT)
|
|
39
|
-
[](https://github.com/tox-dev/sphinx-argparse-cli/actions/workflows/check.yaml)
|
|
40
|
-
|
|
41
|
-
Render CLI arguments (sub-commands friendly) defined by the argparse module. For live demo checkout the documentation of
|
|
42
|
-
[tox](https://tox.wiki/en/latest/cli_interface.html),
|
|
43
|
-
[pypa-build](https://pypa-build.readthedocs.io/en/latest/#python-m-build) and
|
|
44
|
-
[mdpo](https://mondeja.github.io/mdpo/latest/cli.html).
|
|
45
|
-
|
|
46
|
-
## Installation
|
|
47
|
-
|
|
48
|
-
```bash
|
|
49
|
-
python -m pip install sphinx-argparse-cli
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
## Enable in `conf.py`
|
|
53
|
-
|
|
54
|
-
```python
|
|
55
|
-
# just add it to your list of extensions to load within conf.py
|
|
56
|
-
extensions = ["sphinx_argparse_cli"]
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
## use
|
|
60
|
-
|
|
61
|
-
Within the reStructuredText files use the `sphinx_argparse_cli` directive that takes, at least, two arguments:
|
|
62
|
-
|
|
63
|
-
| Name | Description |
|
|
64
|
-
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
65
|
-
| module | the module path to where the parser is defined |
|
|
66
|
-
| func | the name of the function that once called with no arguments constructs the parser |
|
|
67
|
-
| prog | (optional) when provided, overwrites the `<prog>` name. |
|
|
68
|
-
| hook | (optional) hook `argparse` to retrieve the parser if `func` uses a parser instead of returning it. |
|
|
69
|
-
| title | (optional) when provided, overwrites the `<prog> - CLI interface` title added by default and when empty, will not be included |
|
|
70
|
-
| description | (optional) when provided, overwrites the description and when empty, will not be included |
|
|
71
|
-
| epilog | (optional) when provided, overwrites the epilog and when empty, will not be included |
|
|
72
|
-
| usage_width | (optional) how large should usage examples be - defaults to 100 character |
|
|
73
|
-
| usage_first | (optional) show usage before description |
|
|
74
|
-
| group_title_prefix | (optional) groups subsections title prefixes, accepts the string `{prog}` as a replacement for the program name - defaults to `{prog}` |
|
|
75
|
-
| 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}` |
|
|
76
|
-
| no_default_values | (optional) suppresses generation of `default` entries |
|
|
77
|
-
| 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`) |
|
|
78
|
-
|
|
79
|
-
For example:
|
|
80
|
-
|
|
81
|
-
```rst
|
|
82
|
-
.. sphinx_argparse_cli::
|
|
83
|
-
:module: a_project.cli
|
|
84
|
-
:func: build_parser
|
|
85
|
-
:prog: my-cli-program
|
|
86
|
-
```
|
|
87
|
-
|
|
88
|
-
If you have code that creates and uses a parser but does not return it, you can specify the `:hook:` flag:
|
|
89
|
-
|
|
90
|
-
```rst
|
|
91
|
-
.. sphinx_argparse_cli::
|
|
92
|
-
:module: a_project.cli
|
|
93
|
-
:func: main
|
|
94
|
-
:hook:
|
|
95
|
-
:prog: my-cli-program
|
|
96
|
-
```
|
|
97
|
-
|
|
98
|
-
### Refer to generated content
|
|
99
|
-
|
|
100
|
-
The tool will register reference links to all anchors. This means that you can use the sphinx `ref` role to refer to
|
|
101
|
-
both the (sub)command title/groups and every flag/argument. The tool offers a configuration flag
|
|
102
|
-
`sphinx_argparse_cli_prefix_document` (change by setting this variable in `conf.py` - by default `False`). This option
|
|
103
|
-
influences the reference ids generated. If it's false the reference will be the anchor id (the text appearing after the
|
|
104
|
-
`'#` 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
|
|
105
|
-
to avoid reference label clash when the same anchors are generated in multiple documents).
|
|
106
|
-
|
|
107
|
-
For example in case of a `tox` command, and `sphinx_argparse_cli_prefix_document=False` (default):
|
|
108
|
-
|
|
109
|
-
- to refer to the optional arguments group use ``:ref:`tox-optional-arguments` ``,
|
|
110
|
-
- to refer to the run subcommand use ``:ref:`tox-run` ``,
|
|
111
|
-
- to refer to flag `--magic` of the `run` sub-command use ``:ref:`tox-run---magic` ``.
|
|
112
|
-
|
|
113
|
-
For example in case of a `tox` command, and `sphinx_argparse_cli_prefix_document=True`, and the current document name
|
|
114
|
-
being `cli`:
|
|
115
|
-
|
|
116
|
-
- to refer to the optional arguments group use ``:ref:`cli:tox-optional-arguments` ``,
|
|
117
|
-
- to refer to the run subcommand use ``:ref:`cli:tox-run` ``,
|
|
118
|
-
- to refer to flag `--magic` of the `run` sub-command use ``:ref:`cli:tox-run---magic` ``.
|
|
119
|
-
|
|
120
|
-
Due to Sphinx's `:ref:` only supporting lower-case values, if you need to distinguish mixed case program names or
|
|
121
|
-
arguments, set the `:force_refs_lower:` argument. With this flag, captial-letters in references will be converted to
|
|
122
|
-
their lower-case counterpart and prefixed with an `_`. For example:
|
|
123
|
-
|
|
124
|
-
- A `prog` name `SampleProgram` will be referenced as ``:ref:`_sample_program...` ``.
|
|
125
|
-
- To distinguish between mixed case flags `-a` and `-A` use ``:ref:`_sample_program--a` `` and
|
|
126
|
-
``:ref:`_sample_program--_a` `` respectively
|
|
127
|
-
|
|
128
|
-
Note that if you are _not_ concerned about using internal Sphinx `:ref:` cross-references, you may choose to leave this
|
|
129
|
-
off to maintain mixed-case anchors in your output HTML; but be aware that later enabling it will change your anchors in
|
|
130
|
-
the output HTML.
|
|
@@ -1,99 +0,0 @@
|
|
|
1
|
-
# sphinx-argparse-cli
|
|
2
|
-
|
|
3
|
-
[](https://pypi.org/project/sphinx-argparse-cli)
|
|
4
|
-
[](https://pypi.org/project/sphinx-argparse-cli)
|
|
5
|
-
[](https://pypi.org/project/sphinx-argparse-cli)
|
|
6
|
-
[](https://pepy.tech/project/sphinx-argparse-cli)
|
|
7
|
-
[](https://opensource.org/licenses/MIT)
|
|
8
|
-
[](https://github.com/tox-dev/sphinx-argparse-cli/actions/workflows/check.yaml)
|
|
9
|
-
|
|
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).
|
|
14
|
-
|
|
15
|
-
## Installation
|
|
16
|
-
|
|
17
|
-
```bash
|
|
18
|
-
python -m pip install sphinx-argparse-cli
|
|
19
|
-
```
|
|
20
|
-
|
|
21
|
-
## Enable in `conf.py`
|
|
22
|
-
|
|
23
|
-
```python
|
|
24
|
-
# just add it to your list of extensions to load within conf.py
|
|
25
|
-
extensions = ["sphinx_argparse_cli"]
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
## use
|
|
29
|
-
|
|
30
|
-
Within the reStructuredText files use the `sphinx_argparse_cli` directive that takes, at least, two arguments:
|
|
31
|
-
|
|
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`) |
|
|
47
|
-
|
|
48
|
-
For example:
|
|
49
|
-
|
|
50
|
-
```rst
|
|
51
|
-
.. sphinx_argparse_cli::
|
|
52
|
-
:module: a_project.cli
|
|
53
|
-
:func: build_parser
|
|
54
|
-
:prog: my-cli-program
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
If you have code that creates and uses a parser but does not return it, you can specify the `:hook:` flag:
|
|
58
|
-
|
|
59
|
-
```rst
|
|
60
|
-
.. sphinx_argparse_cli::
|
|
61
|
-
:module: a_project.cli
|
|
62
|
-
:func: main
|
|
63
|
-
:hook:
|
|
64
|
-
:prog: my-cli-program
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
### Refer to generated content
|
|
68
|
-
|
|
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).
|
|
75
|
-
|
|
76
|
-
For example in case of a `tox` command, and `sphinx_argparse_cli_prefix_document=False` (default):
|
|
77
|
-
|
|
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` ``.
|
|
81
|
-
|
|
82
|
-
For example in case of a `tox` command, and `sphinx_argparse_cli_prefix_document=True`, and the current document name
|
|
83
|
-
being `cli`:
|
|
84
|
-
|
|
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` ``.
|
|
88
|
-
|
|
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:
|
|
92
|
-
|
|
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
|
|
96
|
-
|
|
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.
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
{sphinx_argparse_cli-1.21.0 → sphinx_argparse_cli-1.21.2}/src/sphinx_argparse_cli/__init__.py
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|