| Name | sphinx-argparse-cli JSON |
| Version |
1.19.0
JSON |
| download |
| home_page | None |
| Summary | render CLI arguments (sub-commands friendly) defined by argparse module |
| upload_time | 2024-12-10 01:44:47 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
argparse
sphinx
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# sphinx-argparse-cli
[](https://pypi.org/project/sphinx-argparse-cli)
[](https://pypi.org/project/sphinx-argparse-cli)
[](https://pypi.org/project/sphinx-argparse-cli)
[](https://pepy.tech/project/sphinx-argparse-cli)
[](https://opensource.org/licenses/MIT)
[](https://github.com/tox-dev/sphinx-argparse-cli/actions/workflows/check.yaml)
Render CLI arguments (sub-commands friendly) defined by the argparse module. For live demo checkout the documentation of
[tox](https://tox.wiki/en/latest/cli_interface.html),
[pypa-build](https://pypa-build.readthedocs.io/en/latest/#python-m-build) and
[mdpo](https://mondeja.github.io/mdpo/latest/cli.html).
## Installation
```bash
python -m pip install sphinx-argparse-cli
```
## Enable in `conf.py`
```python
# just add it to your list of extensions to load within conf.py
extensions = ["sphinx_argparse_cli"]
```
## use
Within the reStructuredText files use the `sphinx_argparse_cli` directive that takes, at least, two arguments:
| Name | Description |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| module | the module path to where the parser is defined |
| func | the name of the function that once called with no arguments constructs the parser |
| prog | (optional) when provided, overwrites the `<prog>` name. |
| hook | (optional) hook `argparse` to retrieve the parser if `func` uses a parser instead of returning it. |
| title | (optional) when provided, overwrites the `<prog> - CLI interface` title added by default and when empty, will not be included |
| description | (optional) when provided, overwrites the description and when empty, will not be included |
| epilog | (optional) when provided, overwrites the epilog and when empty, will not be included |
| usage_width | (optional) how large should usage examples be - defaults to 100 character |
| usage_first | (optional) show usage before description |
| group_title_prefix | (optional) groups subsections title prefixes, accepts the string `{prog}` as a replacement for the program name - defaults to `{prog}` |
| 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}` |
| no_default_values | (optional) suppresses generation of `default` entries |
| 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`) |
For example:
```rst
.. sphinx_argparse_cli::
:module: a_project.cli
:func: build_parser
:prog: my-cli-program
```
If you have code that creates and uses a parser but does not return it, you can specify the `:hook:` flag:
```rst
.. sphinx_argparse_cli::
:module: a_project.cli
:func: main
:hook:
:prog: my-cli-program
```
### Refer to generated content
The tool will register reference links to all anchors. This means that you can use the sphinx `ref` role to refer to
both the (sub)command title/groups and every flag/argument. The tool offers a configuration flag
`sphinx_argparse_cli_prefix_document` (change by setting this variable in `conf.py` - by default `False`). This option
influences the reference ids generated. If it's false the reference will be the anchor id (the text appearing after the
`'#` 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
to avoid reference label clash when the same anchors are generated in multiple documents).
For example in case of a `tox` command, and `sphinx_argparse_cli_prefix_document=False` (default):
- to refer to the optional arguments group use ``:ref:`tox-optional-arguments` ``,
- to refer to the run subcommand use ``:ref:`tox-run` ``,
- to refer to flag `--magic` of the `run` sub-command use ``:ref:`tox-run---magic` ``.
For example in case of a `tox` command, and `sphinx_argparse_cli_prefix_document=True`, and the current document name
being `cli`:
- to refer to the optional arguments group use ``:ref:`cli:tox-optional-arguments` ``,
- to refer to the run subcommand use ``:ref:`cli:tox-run` ``,
- to refer to flag `--magic` of the `run` sub-command use ``:ref:`cli:tox-run---magic` ``.
Due to Sphinx's `:ref:` only supporting lower-case values, if you need to distinguish mixed case program names or
arguments, set the `:force_refs_lower:` argument. With this flag, captial-letters in references will be converted to
their lower-case counterpart and prefixed with an `_`. For example:
- A `prog` name `SampleProgram` will be referenced as ``:ref:`_sample_program...` ``.
- To distinguish between mixed case flags `-a` and `-A` use ``:ref:`_sample_program--a` `` and
``:ref:`_sample_program--_a` `` respectively
Note that if you are _not_ concerned about using internal Sphinx `:ref:` cross-references, you may choose to leave this
off to maintain mixed-case anchors in your output HTML; but be aware that later enabling it will change your anchors in
the output HTML.
Raw data
{
"_id": null,
"home_page": null,
"name": "sphinx-argparse-cli",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Bernat Gabor <gaborjbernat@gmail.com>",
"keywords": "argparse, sphinx",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/32/5f/ae6043738a48408ce1371303958fa02943d29619dd5d202e147b1dc8552d/sphinx_argparse_cli-1.19.0.tar.gz",
"platform": null,
"description": "# sphinx-argparse-cli\n\n[](https://pypi.org/project/sphinx-argparse-cli)\n[](https://pypi.org/project/sphinx-argparse-cli)\n[](https://pypi.org/project/sphinx-argparse-cli)\n[](https://pepy.tech/project/sphinx-argparse-cli)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/tox-dev/sphinx-argparse-cli/actions/workflows/check.yaml)\n\nRender CLI arguments (sub-commands friendly) defined by the argparse module. For live demo checkout the documentation of\n[tox](https://tox.wiki/en/latest/cli_interface.html),\n[pypa-build](https://pypa-build.readthedocs.io/en/latest/#python-m-build) and\n[mdpo](https://mondeja.github.io/mdpo/latest/cli.html).\n\n## Installation\n\n```bash\npython -m pip install sphinx-argparse-cli\n```\n\n## Enable in `conf.py`\n\n```python\n# just add it to your list of extensions to load within conf.py\nextensions = [\"sphinx_argparse_cli\"]\n```\n\n## use\n\nWithin the reStructuredText files use the `sphinx_argparse_cli` directive that takes, at least, two arguments:\n\n| Name | Description |\n| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| module | the module path to where the parser is defined |\n| func | the name of the function that once called with no arguments constructs the parser |\n| prog | (optional) when provided, overwrites the `<prog>` name. |\n| hook | (optional) hook `argparse` to retrieve the parser if `func` uses a parser instead of returning it. |\n| title | (optional) when provided, overwrites the `<prog> - CLI interface` title added by default and when empty, will not be included |\n| description | (optional) when provided, overwrites the description and when empty, will not be included |\n| epilog | (optional) when provided, overwrites the epilog and when empty, will not be included |\n| usage_width | (optional) how large should usage examples be - defaults to 100 character |\n| usage_first | (optional) show usage before description |\n| group_title_prefix | (optional) groups subsections title prefixes, accepts the string `{prog}` as a replacement for the program name - defaults to `{prog}` |\n| 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}` |\n| no_default_values | (optional) suppresses generation of `default` entries |\n| 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`) |\n\nFor example:\n\n```rst\n.. sphinx_argparse_cli::\n :module: a_project.cli\n :func: build_parser\n :prog: my-cli-program\n```\n\nIf you have code that creates and uses a parser but does not return it, you can specify the `:hook:` flag:\n\n```rst\n.. sphinx_argparse_cli::\n :module: a_project.cli\n :func: main\n :hook:\n :prog: my-cli-program\n```\n\n### Refer to generated content\n\nThe tool will register reference links to all anchors. This means that you can use the sphinx `ref` role to refer to\nboth the (sub)command title/groups and every flag/argument. The tool offers a configuration flag\n`sphinx_argparse_cli_prefix_document` (change by setting this variable in `conf.py` - by default `False`). This option\ninfluences the reference ids generated. If it's false the reference will be the anchor id (the text appearing after the\n`'#` 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\nto avoid reference label clash when the same anchors are generated in multiple documents).\n\nFor example in case of a `tox` command, and `sphinx_argparse_cli_prefix_document=False` (default):\n\n- to refer to the optional arguments group use ``:ref:`tox-optional-arguments` ``,\n- to refer to the run subcommand use ``:ref:`tox-run` ``,\n- to refer to flag `--magic` of the `run` sub-command use ``:ref:`tox-run---magic` ``.\n\nFor example in case of a `tox` command, and `sphinx_argparse_cli_prefix_document=True`, and the current document name\nbeing `cli`:\n\n- to refer to the optional arguments group use ``:ref:`cli:tox-optional-arguments` ``,\n- to refer to the run subcommand use ``:ref:`cli:tox-run` ``,\n- to refer to flag `--magic` of the `run` sub-command use ``:ref:`cli:tox-run---magic` ``.\n\nDue to Sphinx's `:ref:` only supporting lower-case values, if you need to distinguish mixed case program names or\narguments, set the `:force_refs_lower:` argument. With this flag, captial-letters in references will be converted to\ntheir lower-case counterpart and prefixed with an `_`. For example:\n\n- A `prog` name `SampleProgram` will be referenced as ``:ref:`_sample_program...` ``.\n- To distinguish between mixed case flags `-a` and `-A` use ``:ref:`_sample_program--a` `` and\n ``:ref:`_sample_program--_a` `` respectively\n\nNote that if you are _not_ concerned about using internal Sphinx `:ref:` cross-references, you may choose to leave this\noff to maintain mixed-case anchors in your output HTML; but be aware that later enabling it will change your anchors in\nthe output HTML.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "render CLI arguments (sub-commands friendly) defined by argparse module",
"version": "1.19.0",
"project_urls": {
"Documentation": "https://github.com/tox-dev/sphinx-argparse-cli#sphinx-argparse-cli",
"Homepage": "https://github.com/tox-dev/sphinx-argparse-cli",
"Source": "https://github.com/tox-dev/sphinx-argparse-cli",
"Tracker": "https://github.com/tox-dev/sphinx-argparse-cli/issues"
},
"split_keywords": [
"argparse",
" sphinx"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "001f7d40169591a70fb1a8ba57345e22c3f6dca5b06ee6efddafe5ccee91336c",
"md5": "52ca1a7adc86bb8cf6ab111e2c7d5a46",
"sha256": "c0e069deed1db44d289f90469c04320f1c2249b3dcbd3c3e093bf9a66e4bd8e4"
},
"downloads": -1,
"filename": "sphinx_argparse_cli-1.19.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "52ca1a7adc86bb8cf6ab111e2c7d5a46",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 9941,
"upload_time": "2024-12-10T01:44:44",
"upload_time_iso_8601": "2024-12-10T01:44:44.738003Z",
"url": "https://files.pythonhosted.org/packages/00/1f/7d40169591a70fb1a8ba57345e22c3f6dca5b06ee6efddafe5ccee91336c/sphinx_argparse_cli-1.19.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "325fae6043738a48408ce1371303958fa02943d29619dd5d202e147b1dc8552d",
"md5": "c7c642b6e709d25b376773903d0df71a",
"sha256": "0374b23560fd4246234c0ef2d8bb97703088c8ae721bf63a84b9fd0d32f87a78"
},
"downloads": -1,
"filename": "sphinx_argparse_cli-1.19.0.tar.gz",
"has_sig": false,
"md5_digest": "c7c642b6e709d25b376773903d0df71a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 12667,
"upload_time": "2024-12-10T01:44:47",
"upload_time_iso_8601": "2024-12-10T01:44:47.429772Z",
"url": "https://files.pythonhosted.org/packages/32/5f/ae6043738a48408ce1371303958fa02943d29619dd5d202e147b1dc8552d/sphinx_argparse_cli-1.19.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-10 01:44:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tox-dev",
"github_project": "sphinx-argparse-cli#sphinx-argparse-cli",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "sphinx-argparse-cli"
}
