sphinx-argparse-cli 1.24.0__tar.gz → 1.24.2__tar.gz

{sphinx_argparse_cli-1.24.0 → sphinx_argparse_cli-1.24.2}/.gitignore

@@ -9,3 +9,4 @@ __pycache__
 build
 dist
 src/sphinx_argparse_cli/version.py
+/uv.lock

{sphinx_argparse_cli-1.24.0 → sphinx_argparse_cli-1.24.2}/PKG-INFO

@@ -1,7 +1,9 @@
 Metadata-Version: 2.5
 Name: sphinx-argparse-cli
-Version: 1.24.0
+Version: 1.24.2
+Import-Name: sphinx_argparse_cli
 Summary: render CLI arguments (sub-commands friendly) defined by argparse module
+Project-URL: Changelog, https://github.com/tox-dev/sphinx-argparse-cli/blob/main/CHANGELOG.md
 Project-URL: Documentation, https://github.com/tox-dev/sphinx-argparse-cli#sphinx-argparse-cli
 Project-URL: Homepage, https://github.com/tox-dev/sphinx-argparse-cli
 Project-URL: Source, https://github.com/tox-dev/sphinx-argparse-cli
@@ -15,7 +17,6 @@ Classifier: Environment :: Console
 Classifier: Framework :: Sphinx
 Classifier: Framework :: Sphinx :: Extension
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.11
@@ -38,9 +39,14 @@ Description-Content-Type: text/markdown
 [![Downloads](https://static.pepy.tech/badge/sphinx-argparse-cli/month)](https://pepy.tech/project/sphinx-argparse-cli)
 [![PyPI - License](https://img.shields.io/pypi/l/sphinx-argparse-cli?style=flat-square)](https://opensource.org/licenses/MIT)
 [![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)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/tox-dev/sphinx-argparse-cli/badge)](https://scorecard.dev/viewer/?uri=github.com/tox-dev/sphinx-argparse-cli)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/16261/badge)](https://www.bestpractices.dev/projects/16261)
 
 Render CLI arguments (sub-commands friendly) defined by the argparse module.
 
+See the [changelog](https://github.com/tox-dev/sphinx-argparse-cli/blob/main/CHANGELOG.md) for released changes. The [contribution guide](https://github.com/tox-dev/sphinx-argparse-cli/blob/main/CONTRIBUTING.md) explains which pull
+requests need a fragment, how to name it, and when to use `skip news`.
+
 ## Getting started
 
 Install the package:

{sphinx_argparse_cli-1.24.0 → sphinx_argparse_cli-1.24.2}/pyproject.toml

@@ -1,14 +1,15 @@
 [build-system]
 build-backend = "hatchling.build"
 requires = [
+  "hatch-fancy-pypi-readme>=25.1",
   "hatch-vcs>=0.5",
   "hatchling>=1.32.4",
 ]
 
 [project]
 name = "sphinx-argparse-cli"
+import-names = [ "sphinx_argparse_cli" ]
 description = "render CLI arguments (sub-commands friendly) defined by argparse module"
-readme = "README.md"
 keywords = [
   "argparse",
   "sphinx",
@@ -24,7 +25,6 @@ classifiers = [
   "Framework :: Sphinx",
   "Framework :: Sphinx :: Extension",
   "Intended Audience :: Developers",
-  "License :: OSI Approved :: MIT License",
   "Operating System :: OS Independent",
   "Programming Language :: Python :: 3 :: Only",
   "Programming Language :: Python :: 3.11",
@@ -37,11 +37,13 @@ classifiers = [
   "Topic :: Documentation :: Sphinx",
 ]
 dynamic = [
+  "readme",
   "version",
 ]
 dependencies = [
   "sphinx>=9.0.4",
 ]
+urls.Changelog = "https://github.com/tox-dev/sphinx-argparse-cli/blob/main/CHANGELOG.md"
 urls.Documentation = "https://github.com/tox-dev/sphinx-argparse-cli#sphinx-argparse-cli"
 urls.Homepage = "https://github.com/tox-dev/sphinx-argparse-cli"
 urls.Source = "https://github.com/tox-dev/sphinx-argparse-cli"
@@ -64,6 +66,13 @@ type = [
   "ty<0.0.25,>=0.0.24",
   { include-group = "test" },
 ]
+build = [
+  "cython>=3",
+  "hatch-fancy-pypi-readme>=25.1",
+  "hatch-vcs>=0.5",
+  "hatchling>=1.32.4",
+  "setuptools>=80",
+]
 lint = [
   "pre-commit-uv>=4.3",
 ]
@@ -72,15 +81,41 @@ pkg-meta = [
   "twine>=7",
   "uv>=0.12.22",
 ]
+release-news = [
+  "release-creator>=4.4",
+  "towncrier>=26.9",
+]
+release-notes = [
+  "release-creator>=4.4",
+]
+release-prepare = [
+  "prek>=0.5",
+  "release-creator>=4.4",
+  "towncrier>=26.9",
+]
 
 [tool.hatch]
 version.source = "vcs"
+metadata.hooks.fancy-pypi-readme.content-type = "text/markdown"
+metadata.hooks.fancy-pypi-readme.fragments = [ { path = "README.md" } ]
+metadata.hooks.fancy-pypi-readme.substitutions = [
+  { pattern = '''(?x)
+    (?<!!)\[(?P<label>[^\]]+)\]\( # Link text, excluding images
+    (?P<path>CHANGELOG\.md|CONTRIBUTING\.md) # Repository files linked from the README
+    \)
+    ''', replacement = '[\g<label>](https://github.com/tox-dev/sphinx-argparse-cli/blob/main/\g<path>)' },
+]
 build.hooks.vcs.version-file = "src/sphinx_argparse_cli/version.py"
 build.targets.sdist.include = [
   "/src",
   "/tests",
 ]
 
+[tool.uv]
+dependency-groups.release-news = { requires-python = ">=3.15" }
+dependency-groups.release-notes = { requires-python = ">=3.15" }
+dependency-groups.release-prepare = { requires-python = ">=3.15" }
+
 [tool.black]
 line-length = 120
 
@@ -147,3 +182,34 @@ paths.source = [
 report.fail_under = 100
 html.show_contexts = true
 html.skip_covered = false
+
+[tool.towncrier]
+name = "sphinx-argparse-cli"
+directory = "changelog.d"
+filename = "CHANGELOG.md"
+template = "release_creator.fragments:template.jinja2"
+title_format = false
+type = [
+  { directory = "feature", name = "Added", showcontent = true },
+  { directory = "change", name = "Changes", showcontent = true },
+  { directory = "bugfix", name = "Fixed", showcontent = true },
+  { directory = "doc", name = "Documentation", showcontent = true },
+  { directory = "breaking", name = "Breaking changes", showcontent = true },
+  { directory = "security", name = "Security", showcontent = true },
+  { directory = "performance", name = "Performance", showcontent = true },
+  { directory = "deprecation", name = "Deprecated", showcontent = true },
+  { directory = "removal", name = "Removed", showcontent = true },
+  { directory = "packaging", name = "Packaging", showcontent = true },
+]
+
+[tool.nab]
+mode = "universal"
+base-group = "project-runtime"
+default-groups = []
+uploaded-prior-to = "P7D"
+decision-order = "stable"
+matrix.python = ">=3.15,<3.16"
+matrix.platforms = [ "linux_x86_64" ]
+# release-creator 4.4.0 needs a seven-day cutoff exception.
+# expires 2026-11-09
+packages.release-creator.uploaded-prior-to = 2026-11-02T21:45:00Z

{sphinx_argparse_cli-1.24.0 → sphinx_argparse_cli-1.24.2}/src/sphinx_argparse_cli/version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.24.0'
-__version_tuple__ = version_tuple = (1, 24, 0)
+__version__ = version = '1.24.2'
+__version_tuple__ = version_tuple = (1, 24, 2)
 
 __commit_id__ = commit_id = None

sphinx_argparse_cli-1.24.0/README.md

@@ -1,225 +0,0 @@
-# sphinx-argparse-cli
-
-[![PyPI](https://img.shields.io/pypi/v/sphinx-argparse-cli?style=flat-square)](https://pypi.org/project/sphinx-argparse-cli)
-[![PyPI - Implementation](https://img.shields.io/pypi/implementation/sphinx-argparse-cli?style=flat-square)](https://pypi.org/project/sphinx-argparse-cli)
-[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/sphinx-argparse-cli?style=flat-square)](https://pypi.org/project/sphinx-argparse-cli)
-[![Downloads](https://static.pepy.tech/badge/sphinx-argparse-cli/month)](https://pepy.tech/project/sphinx-argparse-cli)
-[![PyPI - License](https://img.shields.io/pypi/l/sphinx-argparse-cli?style=flat-square)](https://opensource.org/licenses/MIT)
-[![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)
-
-Render CLI arguments (sub-commands friendly) defined by the argparse module.
-
-## Getting started
-
-Install the package:
-
-```bash
-python -m pip install sphinx-argparse-cli
-```
-
-Add the extension to your `conf.py`:
-
-```python
-extensions = ["sphinx_argparse_cli"]
-```
-
-Use the directive in any reStructuredText file:
-
-```rst
-.. sphinx_argparse_cli::
-  :module: my_project.cli
-  :func: build_parser
-```
-
-`:module:` points to the Python module containing the parser, and `:func:` names a zero-argument function that returns
-an `ArgumentParser`. Build your docs and the full CLI reference appears.
-
-## How-to guides
-
-### Override the program name
-
-By default the program name comes from the parser. Use `:prog:` to replace it:
-
-```rst
-.. sphinx_argparse_cli::
-  :module: my_project.cli
-  :func: build_parser
-  :prog: my-cli
-```
-
-### Hook into a parser that is not returned
-
-When a function creates and uses a parser internally without returning it, set the `:hook:` flag to intercept
-`argparse.ArgumentParser`:
-
-```rst
-.. sphinx_argparse_cli::
-  :module: my_project.cli
-  :func: main
-  :hook:
-  :prog: my-cli
-```
-
-### Customize section titles
-
-Control how group and subcommand headings are rendered with `:group_title_prefix:` and `:group_sub_title_prefix:`. Both
-accept `{prog}` and the sub-title also accepts `{subcommand}`:
-
-```rst
-.. sphinx_argparse_cli::
-  :module: my_project.cli
-  :func: build_parser
-  :group_title_prefix: {prog}
-  :group_sub_title_prefix: {prog} {subcommand}
-```
-
-### Suppress default values
-
-Hide `(default: ...)` annotations from the output:
-
-```rst
-.. sphinx_argparse_cli::
-  :module: my_project.cli
-  :func: build_parser
-  :no_default_values:
-```
-
-### Control usage display
-
-Set the character width for usage lines and optionally show usage before the description:
-
-```rst
-.. sphinx_argparse_cli::
-  :module: my_project.cli
-  :func: build_parser
-  :usage_width: 80
-  :usage_first:
-```
-
-### Override title, description, or epilog
-
-Replace auto-detected values, or pass an empty string to suppress them:
-
-```rst
-.. sphinx_argparse_cli::
-  :module: my_project.cli
-  :func: build_parser
-  :title: Custom Title
-  :description: Custom description text.
-  :epilog:
-```
-
-### Cross-reference generated anchors
-
-The directive registers Sphinx reference labels for every command, group, and flag. Use the `:ref:` role to link to
-them.
-
-With `sphinx_argparse_cli_prefix_document = False` (default):
-
-```rst
-:ref:`tox-optional-arguments`
-:ref:`tox-run`
-:ref:`tox-run---magic`
-```
-
-With `sphinx_argparse_cli_prefix_document = True` (anchors prefixed by document name, avoids clashes across documents):
-
-```rst
-:ref:`cli:tox-optional-arguments`
-:ref:`cli:tox-run`
-:ref:`cli:tox-run---magic`
-```
-
-The anchor text is visible after the `#` in the URL when you click a heading.
-
-Flags and positional arguments are also registered as Sphinx program options, so the `:option:` role works with the
-program (and sub-command) name followed by the argument, or scoped through a `.. program::` directive:
-
-```rst
-:option:`tox --magic`
-:option:`tox run --magic`
-
-.. program:: tox run
-
-:option:`--magic`
-:option:`--magic=value`
-```
-
-`:option:` targets keep their original case, so they do not need `:force_refs_lower:`. They ignore
-`sphinx_argparse_cli_prefix_document`; when two documents render the same program, the role links to the first one
-Sphinx reads.
-
-### Handle mixed-case references
-
-Sphinx `:ref:` only supports lower-case targets. When your program name or flags contain capital letters, set
-`:force_refs_lower:` to convert them. Each upper-case letter becomes its lower-case form prefixed with `_` (e.g. `A`
-becomes `_a`):
-
-```rst
-.. sphinx_argparse_cli::
-  :module: my_project.cli
-  :func: build_parser
-  :force_refs_lower:
-```
-
-For a program named `SampleProgram`:
-
-```rst
-:ref:`_sample_program--a`   .. flag -a
-:ref:`_sample_program--_a`  .. flag -A
-```
-
-If you do not need Sphinx `:ref:` cross-references you can leave this off to keep mixed-case anchors in the HTML output,
-but enabling it later will change existing anchor URLs.
-
-### Write help text as reStructuredText
-
-The directive parses every argument's `help` string as reStructuredText, so inline markup such as a `:ref:` role or
-`**bold**` works. The same applies to characters that carry meaning in reStructuredText: a lone `*` (`match *.py`), a
-trailing `_` (`name_`), backticks, or a trailing `::` produce docutils warnings and fail a build run with `-W`. Escape
-them with a backslash (`match \*.py`) or wrap them in inline literals. Text between matching single quotes, double
-quotes, or braces becomes an inline literal for you, so `pick 'fast' or "slow"` shows `'fast'` and `"slow"` as code.
-
-### Add extra content after generated docs
-
-Any content nested inside the directive is appended after the generated CLI documentation:
-
-```rst
-.. sphinx_argparse_cli::
-  :module: my_project.cli
-  :func: build_parser
-
-  Extra notes or examples rendered after the CLI reference.
-```
-
-## Reference
-
-### Directive options
-
-| Option                     | Type   | Default                  | Description                                                                    |
-| -------------------------- | ------ | ------------------------ | ------------------------------------------------------------------------------ |
-| `:module:`                 | string | **required**             | Python module path where the parser is defined                                 |
-| `:func:`                   | string | **required**             | Zero-argument function that returns an `ArgumentParser`                        |
-| `:prog:`                   | string | parser's `prog`          | Override the displayed program name                                            |
-| `:hook:`                   | flag   | off                      | Intercept `ArgumentParser` instead of expecting `func` to return it            |
-| `:title:`                  | string | `<prog> - CLI interface` | Custom title; empty string suppresses it                                       |
-| `:description:`            | string | parser's description     | Custom description; empty string suppresses it                                 |
-| `:epilog:`                 | string | parser's epilog          | Custom epilog; empty string suppresses it                                      |
-| `:usage_width:`            | int    | `100`                    | Character width for usage lines                                                |
-| `:usage_first:`            | flag   | off                      | Show usage before the description                                              |
-| `:group_title_prefix:`     | string | `{prog}`                 | Heading prefix for groups; `{prog}` is replaced with the program name          |
-| `:group_sub_title_prefix:` | string | `{prog} {subcommand}`    | Heading prefix for subcommand groups; supports `{prog}` and `{subcommand}`     |
-| `:no_default_values:`      | flag   | off                      | Suppress `(default: ...)` annotations                                          |
-| `:force_refs_lower:`       | flag   | off                      | Lower-case reference anchors with `_` prefix for capitals (for `:ref:` compat) |
-
-### Configuration values (`conf.py`)
-
-| Name                                  | Type | Default | Description                                                      |
-| ------------------------------------- | ---- | ------- | ---------------------------------------------------------------- |
-| `sphinx_argparse_cli_prefix_document` | bool | `False` | Prefix reference anchors with the document name to avoid clashes |
-
-## Live examples
-
-- [tox](https://tox.wiki/en/latest/cli_interface.html)
-- [pypa-build](https://pypa-build.readthedocs.io/en/latest/#python-m-build)
-- [mdpo](https://mondeja.github.io/mdpo/latest/cli.html)