Script 'mail_helper' called by obssrc
Hello community,
here is the log from the commit of package python-sphinx-click for
openSUSE:Factory checked in at 2022-12-07 17:34:51
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Comparing /work/SRC/openSUSE:Factory/python-sphinx-click (Old)
and /work/SRC/openSUSE:Factory/.python-sphinx-click.new.1835 (New)
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Package is "python-sphinx-click"
Wed Dec 7 17:34:51 2022 rev:3 rq:1040735 version:4.4.0
Changes:
--------
--- /work/SRC/openSUSE:Factory/python-sphinx-click/python-sphinx-click.changes
2022-11-01 13:42:14.719793018 +0100
+++
/work/SRC/openSUSE:Factory/.python-sphinx-click.new.1835/python-sphinx-click.changes
2022-12-07 17:36:11.532942306 +0100
@@ -1,0 +2,20 @@
+Tue Dec 6 15:46:55 UTC 2022 - Dirk Müller <[email protected]>
+
+- update to 4.4.0:
+ * Add release note for Python 3.11 support
+ * actions: Test Python 3.11
+ * Points to alternative to complement Click-based CLI documentation
+ * Add Sphinx extension classifier
+ * Add pull request template
+ * Trivial setup.py, setup.cfg changes
+ * Render option defaults as literals
+ * Change target Python version used for black
+ * actions: Update to latest versions of actions
+ * Use deep clone for GitHub actions
+ * docs: Add more examples
+ * tests: Add more application tests
+ * Add our first "extension" test
+ * Switch to pytest for testing
+ * Run mypy as part of CI job
+
+-------------------------------------------------------------------
Old:
----
sphinx-click-4.3.0.tar.gz
New:
----
sphinx-click-4.4.0.tar.gz
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Other differences:
------------------
++++++ python-sphinx-click.spec ++++++
--- /var/tmp/diff_new_pack.o3G0Jv/_old 2022-12-07 17:36:11.992944825 +0100
+++ /var/tmp/diff_new_pack.o3G0Jv/_new 2022-12-07 17:36:11.996944847 +0100
@@ -18,7 +18,7 @@
%{?!python_module:%define python_module() python-%{**} python3-%{**}}
Name: python-sphinx-click
-Version: 4.3.0
+Version: 4.4.0
Release: 0
Summary: Sphinx extension that automatically documents click
applications
License: MIT
++++++ sphinx-click-4.3.0.tar.gz -> sphinx-click-4.4.0.tar.gz ++++++
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-click-4.3.0/.github/pull_request_template.md
new/sphinx-click-4.4.0/.github/pull_request_template.md
--- old/sphinx-click-4.3.0/.github/pull_request_template.md 1970-01-01
01:00:00.000000000 +0100
+++ new/sphinx-click-4.4.0/.github/pull_request_template.md 2022-12-06
14:00:28.000000000 +0100
@@ -0,0 +1,16 @@
+## Summary
+
+<!-- Summarise your change here -->
+
+## Tasks
+
+<!-- Mark tasks as complete or not applicable using [x] -->
+
+- [ ] Added unit tests
+- [ ] Added documentation for new features (where applicable)
+- [ ] Added release notes (using [`reno`](https://pypi.org/project/reno/))
+- [ ] Ran test suite and style checks and built documentation (`tox`)
+
+## Further details
+
+<!-- Note any further details here, where applicable -->
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-click-4.3.0/.github/workflows/ci.yaml
new/sphinx-click-4.4.0/.github/workflows/ci.yaml
--- old/sphinx-click-4.3.0/.github/workflows/ci.yaml 2022-07-04
13:00:24.000000000 +0200
+++ new/sphinx-click-4.4.0/.github/workflows/ci.yaml 2022-12-06
14:00:28.000000000 +0100
@@ -9,26 +9,29 @@
runs-on: ubuntu-latest
steps:
- name: Checkout source code
- uses: actions/checkout@v2
- - name: Set up Python 3.10
- uses: actions/setup-python@v2
+ uses: actions/checkout@v3
+ - name: Set up Python 3.11
+ uses: actions/setup-python@v4
with:
- python-version: "3.10"
+ python-version: "3.11"
- name: Install dependencies
run: python -m pip install tox
- name: Run tox
- run: tox -e style
+ run: tox -e style,mypy
test:
name: Run unit tests
runs-on: ubuntu-latest
strategy:
matrix:
- python: ["3.7", "3.8", "3.9", "3.10"]
+ python: ["3.7", "3.8", "3.9", "3.10", "3.11"]
steps:
- name: Checkout source code
- uses: actions/checkout@v2
+ uses: actions/checkout@v3
+ # We need history to build the package
+ with:
+ fetch-depth: 0
- name: Set up Python ${{ matrix.python }}
- uses: actions/setup-python@v2
+ uses: actions/setup-python@v4
with:
python-version: ${{ matrix.python }}
- name: Install dependencies
@@ -41,19 +44,20 @@
runs-on: ubuntu-latest
steps:
- name: Checkout source code
- uses: actions/checkout@v2
+ uses: actions/checkout@v3
+ # We need history for release notes
with:
fetch-depth: 0
- - name: Set up Python 3.10
- uses: actions/setup-python@v2
+ - name: Set up Python 3.11
+ uses: actions/setup-python@v4
with:
- python-version: "3.10"
+ python-version: "3.11"
- name: Install dependencies
run: python -m pip install tox
- name: Build docs (via tox)
run: tox -e docs
- name: Archive build results
- uses: actions/upload-artifact@v2
+ uses: actions/upload-artifact@v3
with:
name: html-docs-build
path: docs/_build/html
@@ -65,13 +69,14 @@
if: github.event_name == 'push'
steps:
- name: Checkout source code
- uses: actions/checkout@v2
+ uses: actions/checkout@v3
+ # We need history to build the package
with:
fetch-depth: 0
- - name: Set up Python 3.10
- uses: actions/setup-python@v2
+ - name: Set up Python 3.11
+ uses: actions/setup-python@v4
with:
- python-version: "3.10"
+ python-version: "3.11"
- name: Install dependencies
run: python -m pip install build
- name: Build a binary wheel and a source tarball
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-click-4.3.0/AUTHORS
new/sphinx-click-4.4.0/AUTHORS
--- old/sphinx-click-4.3.0/AUTHORS 2022-07-04 13:00:34.000000000 +0200
+++ new/sphinx-click-4.4.0/AUTHORS 2022-12-06 14:00:46.000000000 +0100
@@ -9,9 +9,11 @@
Giel van Schijndel <[email protected]>
Hugo Osvaldo Barrera <[email protected]>
James Ennis <[email protected]>
+Jared Dillard <[email protected]>
JeremyB <[email protected]>
Jiri Kuncar <[email protected]>
José Sánchez-Gallego <[email protected]>
+Kevin Deldycke <[email protected]>
Lev Gorodetskiy <[email protected]>
Maarten ter Huurne <[email protected]>
Miro HronÄok <[email protected]>
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-click-4.3.0/ChangeLog
new/sphinx-click-4.4.0/ChangeLog
--- old/sphinx-click-4.3.0/ChangeLog 2022-07-04 13:00:34.000000000 +0200
+++ new/sphinx-click-4.4.0/ChangeLog 2022-12-06 14:00:46.000000000 +0100
@@ -1,6 +1,25 @@
CHANGES
=======
+4.4.0
+-----
+
+* Add release note for Python 3.11 support
+* actions: Test Python 3.11
+* Points to alternative to complement Click-based CLI documentation
+* Add Sphinx extension classifier
+* Add pull request template
+* Trivial setup.py, setup.cfg changes
+* Render option defaults as literals
+* Change target Python version used for black
+* actions: Update to latest versions of actions
+* Use deep clone for GitHub actions
+* docs: Add more examples
+* tests: Add more application tests
+* Add our first "extension" test
+* Switch to pytest for testing
+* Run mypy as part of CI job
+
4.3.0
-----
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-click-4.3.0/PKG-INFO
new/sphinx-click-4.4.0/PKG-INFO
--- old/sphinx-click-4.3.0/PKG-INFO 2022-07-04 13:00:34.414166000 +0200
+++ new/sphinx-click-4.4.0/PKG-INFO 2022-12-06 14:00:46.728331300 +0100
@@ -1,6 +1,6 @@
Metadata-Version: 2.1
Name: sphinx-click
-Version: 4.3.0
+Version: 4.4.0
Summary: Sphinx extension that automatically documents click applications
Home-page: https://github.com/click-contrib/sphinx-click
Author: Stephen Finucane
@@ -12,6 +12,7 @@
Keywords: sphinx
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
+Classifier: Framework :: Sphinx :: Extension
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
@@ -19,6 +20,8 @@
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Documentation
+Classifier: Topic :: Utilities
Requires-Python: >=3.7
Description-Content-Type: text/x-rst; charset=UTF-8
License-File: LICENSE
@@ -35,8 +38,8 @@
:target: https://sphinx-click.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
-`sphinx-click` is a `Sphinx`__ plugin that allows you to automatically extract
-documentation from a `click-based`__ application and include it in your docs.
+``sphinx-click`` is a `Sphinx`__ plugin that allows you to automatically
extract
+documentation from a `Click-based`__ application and include it in your docs.
__ http://www.sphinx-doc.org/
__ http://click.pocoo.org/
@@ -44,13 +47,13 @@
Installation
------------
-Install the plugin using `pip`:
+Install the plugin using ``pip``:
.. code-block:: shell
$ pip install sphinx-click
-Alternatively, install from source by cloning this repo then running `pip`
+Alternatively, install from source by cloning this repo then running ``pip``
locally:
.. code-block:: shell
@@ -62,10 +65,10 @@
.. important::
- To document a click-based application, both the application itself and any
+ To document a Click-based application, both the application itself and any
additional dependencies required by that application **must be installed**.
-Enable the plugin in your Sphinx `conf.py` file:
+Enable the plugin in your Sphinx ``conf.py``` file:
.. code-block:: python
@@ -83,3 +86,19 @@
Detailed information on the various options available is provided in the
`documentation <https://sphinx-click.readthedocs.io>`_.
+Alternative
+-----------
+
+This plugin is perfect to document a Click-based CLI in Sphinx, as it properly
+renders the help screen and its options in nice HTML with deep links and
+styling.
+
+However, if you are looking to document the source code of a Click-based CLI,
+and the result of its execution, you might want to check out `click-extra`__.
+The latter provides the ``.. click:example::`` and ``.. click:run::`` Sphinx
+directives so you can `capture and render, with full colors, the result of your
+CLI in your documentation`__.
+
+__ https://github.com/kdeldycke/click-extra/
+__ https://kdeldycke.github.io/click-extra/sphinx.html
+
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-click-4.3.0/README.rst
new/sphinx-click-4.4.0/README.rst
--- old/sphinx-click-4.3.0/README.rst 2022-07-04 13:00:24.000000000 +0200
+++ new/sphinx-click-4.4.0/README.rst 2022-12-06 14:00:28.000000000 +0100
@@ -10,8 +10,8 @@
:target: https://sphinx-click.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
-`sphinx-click` is a `Sphinx`__ plugin that allows you to automatically extract
-documentation from a `click-based`__ application and include it in your docs.
+``sphinx-click`` is a `Sphinx`__ plugin that allows you to automatically
extract
+documentation from a `Click-based`__ application and include it in your docs.
__ http://www.sphinx-doc.org/
__ http://click.pocoo.org/
@@ -19,13 +19,13 @@
Installation
------------
-Install the plugin using `pip`:
+Install the plugin using ``pip``:
.. code-block:: shell
$ pip install sphinx-click
-Alternatively, install from source by cloning this repo then running `pip`
+Alternatively, install from source by cloning this repo then running ``pip``
locally:
.. code-block:: shell
@@ -37,10 +37,10 @@
.. important::
- To document a click-based application, both the application itself and any
+ To document a Click-based application, both the application itself and any
additional dependencies required by that application **must be installed**.
-Enable the plugin in your Sphinx `conf.py` file:
+Enable the plugin in your Sphinx ``conf.py``` file:
.. code-block:: python
@@ -57,3 +57,19 @@
Detailed information on the various options available is provided in the
`documentation <https://sphinx-click.readthedocs.io>`_.
+
+Alternative
+-----------
+
+This plugin is perfect to document a Click-based CLI in Sphinx, as it properly
+renders the help screen and its options in nice HTML with deep links and
+styling.
+
+However, if you are looking to document the source code of a Click-based CLI,
+and the result of its execution, you might want to check out `click-extra`__.
+The latter provides the ``.. click:example::`` and ``.. click:run::`` Sphinx
+directives so you can `capture and render, with full colors, the result of your
+CLI in your documentation`__.
+
+__ https://github.com/kdeldycke/click-extra/
+__ https://kdeldycke.github.io/click-extra/sphinx.html
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore'
old/sphinx-click-4.3.0/docs/examples/commandcollections.rst
new/sphinx-click-4.4.0/docs/examples/commandcollections.rst
--- old/sphinx-click-4.3.0/docs/examples/commandcollections.rst 2022-07-04
13:00:24.000000000 +0200
+++ new/sphinx-click-4.4.0/docs/examples/commandcollections.rst 2022-12-06
14:00:28.000000000 +0100
@@ -1,5 +1,5 @@
-Documenting |CommandCollection|
-=================================
+Documenting command collections
+===============================
Consider the following sample application, using |CommandCollection|_:
@@ -13,12 +13,13 @@
:prog: cli
:nested: full
+The rendered example is shown below.
+
----
.. click:: commandcollections.cli:cli
:prog: cli
:nested: full
-
.. |CommandCollection| replace:: ``CommandCollection``
.. _CommandCollection:
https://click.palletsprojects.com/en/7.x/api/#click.CommandCollection
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-click-4.3.0/docs/examples/commands.rst
new/sphinx-click-4.4.0/docs/examples/commands.rst
--- old/sphinx-click-4.3.0/docs/examples/commands.rst 1970-01-01
01:00:00.000000000 +0100
+++ new/sphinx-click-4.4.0/docs/examples/commands.rst 2022-12-06
14:00:28.000000000 +0100
@@ -0,0 +1,25 @@
+Documenting commands
+====================
+
+Consider the following sample application, using |Command|_:
+
+.. literalinclude:: ../../examples/commands/cli.py
+
+This can be documented using *sphinx-click* like so:
+
+.. code-block:: rst
+
+ .. click:: commands.cli:cli
+ :prog: cli
+ :nested: full
+
+The rendered example is shown below.
+
+----
+
+.. click:: commands.cli:cli
+ :prog: cli
+ :nested: full
+
+.. |Command| replace:: ``Command``
+.. _Command: https://click.palletsprojects.com/en/7.x/api/#click.Command
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-click-4.3.0/docs/examples/groups.rst
new/sphinx-click-4.4.0/docs/examples/groups.rst
--- old/sphinx-click-4.3.0/docs/examples/groups.rst 1970-01-01
01:00:00.000000000 +0100
+++ new/sphinx-click-4.4.0/docs/examples/groups.rst 2022-12-06
14:00:28.000000000 +0100
@@ -0,0 +1,25 @@
+Documenting groups
+==================
+
+Consider the following sample application, using |Group|_:
+
+.. literalinclude:: ../../examples/groups/cli.py
+
+This can be documented using *sphinx-click* like so:
+
+.. code-block:: rst
+
+ .. click:: groups.cli:cli
+ :prog: cli
+ :nested: full
+
+The rendered example is shown below.
+
+----
+
+.. click:: groups.cli:cli
+ :prog: cli
+ :nested: full
+
+.. |Group| replace:: ``Groups``
+.. _Group: https://click.palletsprojects.com/en/7.x/api/#click.Group
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-click-4.3.0/docs/examples/index.rst
new/sphinx-click-4.4.0/docs/examples/index.rst
--- old/sphinx-click-4.3.0/docs/examples/index.rst 2022-07-04
13:00:24.000000000 +0200
+++ new/sphinx-click-4.4.0/docs/examples/index.rst 2022-12-06
14:00:28.000000000 +0100
@@ -3,6 +3,7 @@
.. toctree::
:maxdepth: 1
- :glob:
- *
+ commands
+ groups
+ commandcollections
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore'
old/sphinx-click-4.3.0/examples/commandcollections/cli.py
new/sphinx-click-4.4.0/examples/commandcollections/cli.py
--- old/sphinx-click-4.3.0/examples/commandcollections/cli.py 2022-07-04
13:00:24.000000000 +0200
+++ new/sphinx-click-4.4.0/examples/commandcollections/cli.py 2022-12-06
14:00:28.000000000 +0100
@@ -4,9 +4,11 @@
main = click.Group(
name='Principal Commands',
- help="Principal commands that are used in ``cli``.\n\n"
- "The section name and description are obtained using the name and "
- "description of the group passed as sources for |CommandCollection|_.",
+ help=(
+ "Principal commands that are used in ``cli``.\n\n"
+ "The section name and description are obtained using the name and "
+ "description of the group passed as sources for |CommandCollection|_."
+ ),
)
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-click-4.3.0/examples/commands/cli.py
new/sphinx-click-4.4.0/examples/commands/cli.py
--- old/sphinx-click-4.3.0/examples/commands/cli.py 1970-01-01
01:00:00.000000000 +0100
+++ new/sphinx-click-4.4.0/examples/commands/cli.py 2022-12-06
14:00:28.000000000 +0100
@@ -0,0 +1,27 @@
+# file: cli.py
+import click
+
+
[email protected]()
[email protected]('--param', envvar='PARAM', help='A sample option')
[email protected]('--another', metavar='[FOO]', help='Another option')
[email protected](
+ '--choice',
+ help='A sample option with choices',
+ type=click.Choice(['Option1', 'Option2']),
+)
[email protected](
+ '--numeric-choice',
+ metavar='<choice>',
+ help='A sample option with numeric choices',
+ type=click.Choice([1, 2, 3]),
+)
[email protected](
+ '--flag',
+ is_flag=True,
+ help='A boolean flag',
+)
[email protected]('ARG', envvar='ARG')
+def cli(bar):
+ """A sample command."""
+ pass
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-click-4.3.0/examples/groups/cli.py
new/sphinx-click-4.4.0/examples/groups/cli.py
--- old/sphinx-click-4.3.0/examples/groups/cli.py 1970-01-01
01:00:00.000000000 +0100
+++ new/sphinx-click-4.4.0/examples/groups/cli.py 2022-12-06
14:00:28.000000000 +0100
@@ -0,0 +1,22 @@
+# file: cli.py
+import click
+
+
[email protected]()
[email protected](
+ '--debug',
+ default=False,
+ is_flag=True,
+ help="Output more information about what's going on.",
+)
+def cli():
+ """A sample command group."""
+ pass
+
+
[email protected]()
[email protected]('--param', envvar='PARAM', help='A sample option')
[email protected]('--another', metavar='[FOO]', help='Another option')
+def hello():
+ """A sample command."""
+ pass
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-click-4.3.0/pyproject.toml
new/sphinx-click-4.4.0/pyproject.toml
--- old/sphinx-click-4.3.0/pyproject.toml 2022-07-04 13:00:24.000000000
+0200
+++ new/sphinx-click-4.4.0/pyproject.toml 2022-12-06 14:00:28.000000000
+0100
@@ -1,6 +1,6 @@
[tool.black]
line-length = 88
-target-version = ['py36']
+target-version = ['py37']
skip-string-normalization = true
exclude = '''
(
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore'
old/sphinx-click-4.3.0/releasenotes/notes/python-3.11-support-64013e70ae9926f4.yaml
new/sphinx-click-4.4.0/releasenotes/notes/python-3.11-support-64013e70ae9926f4.yaml
---
old/sphinx-click-4.3.0/releasenotes/notes/python-3.11-support-64013e70ae9926f4.yaml
1970-01-01 01:00:00.000000000 +0100
+++
new/sphinx-click-4.4.0/releasenotes/notes/python-3.11-support-64013e70ae9926f4.yaml
2022-12-06 14:00:28.000000000 +0100
@@ -0,0 +1,4 @@
+---
+features:
+ - |
+ Python 3.11 is now officially supported.
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-click-4.3.0/setup.cfg
new/sphinx-click-4.4.0/setup.cfg
--- old/sphinx-click-4.3.0/setup.cfg 2022-07-04 13:00:34.418166000 +0200
+++ new/sphinx-click-4.4.0/setup.cfg 2022-12-06 14:00:46.728331300 +0100
@@ -14,6 +14,7 @@
classifiers =
Development Status :: 5 - Production/Stable
Environment :: Console
+ Framework :: Sphinx :: Extension
Intended Audience :: Developers
Intended Audience :: Information Technology
License :: OSI Approved :: MIT License
@@ -21,6 +22,8 @@
Programming Language :: Python
Programming Language :: Python :: 3
Programming Language :: Python :: 3 :: Only
+ Topic :: Documentation
+ Topic :: Utilities
python_requires = >=3.7
keywords = sphinx
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-click-4.3.0/setup.py
new/sphinx-click-4.4.0/setup.py
--- old/sphinx-click-4.3.0/setup.py 2022-07-04 13:00:24.000000000 +0200
+++ new/sphinx-click-4.4.0/setup.py 2022-12-06 14:00:28.000000000 +0100
@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
from setuptools import setup
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-click-4.3.0/sphinx_click/ext.py
new/sphinx-click-4.4.0/sphinx_click/ext.py
--- old/sphinx-click-4.3.0/sphinx_click/ext.py 2022-07-04 13:00:24.000000000
+0200
+++ new/sphinx-click-4.4.0/sphinx_click/ext.py 2022-12-06 14:00:28.000000000
+0100
@@ -83,10 +83,10 @@
# Starting from Click 7.0 show_default can be a string. This is
# mostly useful when the default is not a constant and
# documentation thus needs a manually written string.
- extras.append(':default: %s' % opt.show_default)
+ extras.append(':default: ``%s``' % opt.show_default)
elif opt.default is not None and opt.show_default:
extras.append(
- ':default: %s'
+ ':default: ``%s``'
% (
', '.join(str(d) for d in opt.default)
if isinstance(opt.default, (list, tuple))
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-click-4.3.0/sphinx_click.egg-info/PKG-INFO
new/sphinx-click-4.4.0/sphinx_click.egg-info/PKG-INFO
--- old/sphinx-click-4.3.0/sphinx_click.egg-info/PKG-INFO 2022-07-04
13:00:34.000000000 +0200
+++ new/sphinx-click-4.4.0/sphinx_click.egg-info/PKG-INFO 2022-12-06
14:00:46.000000000 +0100
@@ -1,6 +1,6 @@
Metadata-Version: 2.1
Name: sphinx-click
-Version: 4.3.0
+Version: 4.4.0
Summary: Sphinx extension that automatically documents click applications
Home-page: https://github.com/click-contrib/sphinx-click
Author: Stephen Finucane
@@ -12,6 +12,7 @@
Keywords: sphinx
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
+Classifier: Framework :: Sphinx :: Extension
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
@@ -19,6 +20,8 @@
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Documentation
+Classifier: Topic :: Utilities
Requires-Python: >=3.7
Description-Content-Type: text/x-rst; charset=UTF-8
License-File: LICENSE
@@ -35,8 +38,8 @@
:target: https://sphinx-click.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
-`sphinx-click` is a `Sphinx`__ plugin that allows you to automatically extract
-documentation from a `click-based`__ application and include it in your docs.
+``sphinx-click`` is a `Sphinx`__ plugin that allows you to automatically
extract
+documentation from a `Click-based`__ application and include it in your docs.
__ http://www.sphinx-doc.org/
__ http://click.pocoo.org/
@@ -44,13 +47,13 @@
Installation
------------
-Install the plugin using `pip`:
+Install the plugin using ``pip``:
.. code-block:: shell
$ pip install sphinx-click
-Alternatively, install from source by cloning this repo then running `pip`
+Alternatively, install from source by cloning this repo then running ``pip``
locally:
.. code-block:: shell
@@ -62,10 +65,10 @@
.. important::
- To document a click-based application, both the application itself and any
+ To document a Click-based application, both the application itself and any
additional dependencies required by that application **must be installed**.
-Enable the plugin in your Sphinx `conf.py` file:
+Enable the plugin in your Sphinx ``conf.py``` file:
.. code-block:: python
@@ -83,3 +86,19 @@
Detailed information on the various options available is provided in the
`documentation <https://sphinx-click.readthedocs.io>`_.
+Alternative
+-----------
+
+This plugin is perfect to document a Click-based CLI in Sphinx, as it properly
+renders the help screen and its options in nice HTML with deep links and
+styling.
+
+However, if you are looking to document the source code of a Click-based CLI,
+and the result of its execution, you might want to check out `click-extra`__.
+The latter provides the ``.. click:example::`` and ``.. click:run::`` Sphinx
+directives so you can `capture and render, with full colors, the result of your
+CLI in your documentation`__.
+
+__ https://github.com/kdeldycke/click-extra/
+__ https://kdeldycke.github.io/click-extra/sphinx.html
+
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-click-4.3.0/sphinx_click.egg-info/SOURCES.txt
new/sphinx-click-4.4.0/sphinx_click.egg-info/SOURCES.txt
--- old/sphinx-click-4.3.0/sphinx_click.egg-info/SOURCES.txt 2022-07-04
13:00:34.000000000 +0200
+++ new/sphinx-click-4.4.0/sphinx_click.egg-info/SOURCES.txt 2022-12-06
14:00:46.000000000 +0100
@@ -9,6 +9,7 @@
setup.cfg
setup.py
tox.ini
+.github/pull_request_template.md
.github/workflows/ci.yaml
docs/changelog.rst
docs/conf.py
@@ -17,11 +18,16 @@
docs/installation.rst
docs/usage.rst
docs/examples/commandcollections.rst
+docs/examples/commands.rst
+docs/examples/groups.rst
docs/examples/index.rst
examples/setup.py
examples/commandcollections/__init__.py
examples/commandcollections/cli.py
+examples/commands/cli.py
+examples/groups/cli.py
releasenotes/notes/add-auto_envvar_prefix-support-a08e68aba792ee26.yaml
+releasenotes/notes/python-3.11-support-64013e70ae9926f4.yaml
sphinx_click/__init__.py
sphinx_click/ext.py
sphinx_click.egg-info/PKG-INFO
@@ -32,4 +38,12 @@
sphinx_click.egg-info/requires.txt
sphinx_click.egg-info/top_level.txt
tests/__init__.py
-tests/test_formatter.py
\ No newline at end of file
+tests/conftest.py
+tests/test_extension.py
+tests/test_formatter.py
+tests/roots/basics/conf.py
+tests/roots/basics/greet.py
+tests/roots/basics/index.rst
+tests/roots/nested-full/conf.py
+tests/roots/nested-full/greet.py
+tests/roots/nested-full/index.rst
\ No newline at end of file
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-click-4.3.0/sphinx_click.egg-info/pbr.json
new/sphinx-click-4.4.0/sphinx_click.egg-info/pbr.json
--- old/sphinx-click-4.3.0/sphinx_click.egg-info/pbr.json 2022-07-04
13:00:34.000000000 +0200
+++ new/sphinx-click-4.4.0/sphinx_click.egg-info/pbr.json 2022-12-06
14:00:46.000000000 +0100
@@ -1 +1 @@
-{"git_version": "3ff77a7", "is_release": false}
\ No newline at end of file
+{"git_version": "0b81d33", "is_release": false}
\ No newline at end of file
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-click-4.3.0/tests/conftest.py
new/sphinx-click-4.4.0/tests/conftest.py
--- old/sphinx-click-4.3.0/tests/conftest.py 1970-01-01 01:00:00.000000000
+0100
+++ new/sphinx-click-4.4.0/tests/conftest.py 2022-12-06 14:00:28.000000000
+0100
@@ -0,0 +1,19 @@
+import shutil
+
+import pytest
+from sphinx.testing import path
+
+# this is necessary because Sphinx isn't exposing its fixtures
+#
https://docs.pytest.org/en/7.1.x/how-to/writing_plugins.html#requiring-loading-plugins-in-a-test-module-or-conftest-file
+pytest_plugins = ['sphinx.testing.fixtures']
+
+
[email protected]
+def rootdir(tmpdir):
+ src = path.path(__file__).parent.abspath() / 'roots'
+ dst = tmpdir.join('roots')
+ shutil.copytree(src, dst)
+ roots = path.path(dst)
+ print(dst)
+ yield roots
+ shutil.rmtree(dst)
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-click-4.3.0/tests/roots/basics/conf.py
new/sphinx-click-4.4.0/tests/roots/basics/conf.py
--- old/sphinx-click-4.3.0/tests/roots/basics/conf.py 1970-01-01
01:00:00.000000000 +0100
+++ new/sphinx-click-4.4.0/tests/roots/basics/conf.py 2022-12-06
14:00:28.000000000 +0100
@@ -0,0 +1,6 @@
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+extensions = ['sphinx_click']
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-click-4.3.0/tests/roots/basics/greet.py
new/sphinx-click-4.4.0/tests/roots/basics/greet.py
--- old/sphinx-click-4.3.0/tests/roots/basics/greet.py 1970-01-01
01:00:00.000000000 +0100
+++ new/sphinx-click-4.4.0/tests/roots/basics/greet.py 2022-12-06
14:00:28.000000000 +0100
@@ -0,0 +1,22 @@
+"""The greet example taken from the README."""
+
+import click
+
+
[email protected]()
+def greet():
+ """A sample command group."""
+ pass
+
+
[email protected]()
[email protected]('user', envvar='USER')
+def hello(user):
+ """Greet a user."""
+ click.echo('Hello %s' % user)
+
+
[email protected]()
+def world():
+ """Greet the world."""
+ click.echo('Hello world!')
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-click-4.3.0/tests/roots/basics/index.rst
new/sphinx-click-4.4.0/tests/roots/basics/index.rst
--- old/sphinx-click-4.3.0/tests/roots/basics/index.rst 1970-01-01
01:00:00.000000000 +0100
+++ new/sphinx-click-4.4.0/tests/roots/basics/index.rst 2022-12-06
14:00:28.000000000 +0100
@@ -0,0 +1,5 @@
+Basics
+======
+
+.. click:: greet:greet
+ :prog: greet
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-click-4.3.0/tests/roots/nested-full/conf.py
new/sphinx-click-4.4.0/tests/roots/nested-full/conf.py
--- old/sphinx-click-4.3.0/tests/roots/nested-full/conf.py 1970-01-01
01:00:00.000000000 +0100
+++ new/sphinx-click-4.4.0/tests/roots/nested-full/conf.py 2022-12-06
14:00:28.000000000 +0100
@@ -0,0 +1,6 @@
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+extensions = ['sphinx_click']
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-click-4.3.0/tests/roots/nested-full/greet.py
new/sphinx-click-4.4.0/tests/roots/nested-full/greet.py
--- old/sphinx-click-4.3.0/tests/roots/nested-full/greet.py 1970-01-01
01:00:00.000000000 +0100
+++ new/sphinx-click-4.4.0/tests/roots/nested-full/greet.py 2022-12-06
14:00:28.000000000 +0100
@@ -0,0 +1,22 @@
+"""The greet example taken from the README."""
+
+import click
+
+
[email protected]()
+def greet():
+ """A sample command group."""
+ pass
+
+
[email protected]()
[email protected]('user', envvar='USER')
+def hello(user):
+ """Greet a user."""
+ click.echo('Hello %s' % user)
+
+
[email protected]()
+def world():
+ """Greet the world."""
+ click.echo('Hello world!')
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-click-4.3.0/tests/roots/nested-full/index.rst
new/sphinx-click-4.4.0/tests/roots/nested-full/index.rst
--- old/sphinx-click-4.3.0/tests/roots/nested-full/index.rst 1970-01-01
01:00:00.000000000 +0100
+++ new/sphinx-click-4.4.0/tests/roots/nested-full/index.rst 2022-12-06
14:00:28.000000000 +0100
@@ -0,0 +1,6 @@
+Basics
+======
+
+.. click:: greet:greet
+ :prog: greet
+ :nested: full
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-click-4.3.0/tests/test_extension.py
new/sphinx-click-4.4.0/tests/test_extension.py
--- old/sphinx-click-4.3.0/tests/test_extension.py 1970-01-01
01:00:00.000000000 +0100
+++ new/sphinx-click-4.4.0/tests/test_extension.py 2022-12-06
14:00:28.000000000 +0100
@@ -0,0 +1,104 @@
+import pickle
+
+from docutils import nodes
+from sphinx import addnodes as sphinx_nodes
+
+
+def test_basics(make_app, rootdir):
+ srcdir = rootdir / 'basics'
+ app = make_app('xml', srcdir=srcdir)
+ app.build()
+
+ # TODO: rather than using the pickled doctree, we should decode the XML
+ content = pickle.loads((app.doctreedir / 'index.doctree').read_bytes())
+
+ # doc has format like so:
+ #
+ # document:
+ # section:
+ # title:
+ # section:
+ # title:
+ # paragraph:
+ # literal_block:
+ # rubric:
+ # index:
+ # desc:
+ # desc_signature:
+ # desc_signature:
+ # index:
+ # desc:
+ # desc_signature:
+ # desc_signature:
+
+ section = content[0][1]
+ assert isinstance(section, nodes.section)
+
+ assert isinstance(section[0], nodes.title)
+ assert section[0].astext() == 'greet'
+ assert isinstance(section[1], nodes.paragraph)
+ assert section[1].astext() == 'A sample command group.'
+ assert isinstance(section[2], nodes.literal_block)
+
+ assert isinstance(section[3], nodes.rubric)
+ assert section[3].astext() == 'Commands'
+ assert isinstance(section[4], sphinx_nodes.index)
+ assert isinstance(section[5], sphinx_nodes.desc)
+ assert isinstance(section[6], sphinx_nodes.index)
+ assert isinstance(section[7], sphinx_nodes.desc)
+
+
+def test_nested_full(make_app, rootdir):
+ srcdir = rootdir / 'nested-full'
+ app = make_app('xml', srcdir=srcdir)
+ app.build()
+
+ # TODO: rather than using the pickled doctree, we should decode the XML
+ content = pickle.loads((app.doctreedir / 'index.doctree').read_bytes())
+
+ # doc has format like so:
+ #
+ # document:
+ # section:
+ # title:
+ # section:
+ # title:
+ # paragraph:
+ # literal_block:
+ # section:
+ # title
+ # paragraph
+ # literal_block
+ # ...
+ # section:
+ # title
+ # paragraph
+ # literal_block
+
+ section = content[0][1]
+ assert isinstance(section, nodes.section)
+
+ assert isinstance(section[0], nodes.title)
+ assert section[0].astext() == 'greet'
+ assert isinstance(section[1], nodes.paragraph)
+ assert section[1].astext() == 'A sample command group.'
+ assert isinstance(section[2], nodes.literal_block)
+
+ subsection_a = section[3]
+ assert isinstance(subsection_a, nodes.section)
+
+ assert isinstance(subsection_a[0], nodes.title)
+ assert subsection_a[0].astext() == 'hello'
+ assert isinstance(subsection_a[1], nodes.paragraph)
+ assert subsection_a[1].astext() == 'Greet a user.'
+ assert isinstance(subsection_a[2], nodes.literal_block)
+ # we don't need to verify the rest of this: that's done elsewhere
+
+ subsection_b = section[4]
+ assert isinstance(subsection_b, nodes.section)
+
+ assert isinstance(subsection_b[0], nodes.title)
+ assert subsection_b[0].astext() == 'world'
+ assert isinstance(subsection_b[1], nodes.paragraph)
+ assert subsection_b[1].astext() == 'Greet the world.'
+ assert isinstance(subsection_b[2], nodes.literal_block)
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-click-4.3.0/tests/test_formatter.py
new/sphinx-click-4.4.0/tests/test_formatter.py
--- old/sphinx-click-4.3.0/tests/test_formatter.py 2022-07-04
13:00:24.000000000 +0200
+++ new/sphinx-click-4.4.0/tests/test_formatter.py 2022-12-06
14:00:28.000000000 +0100
@@ -213,19 +213,19 @@
.. option:: --num-param <num_param>
- :default: 42
+ :default: ``42``
.. option:: --param <param>
- :default: Something computed at runtime
+ :default: ``Something computed at runtime``
.. option:: --group <group>
- :default: ('foo', 'bar')
+ :default: ``('foo', 'bar')``
.. option:: --only-show-default <only_show_default>
- :default: Some default computed at runtime!
+ :default: ``Some default computed at runtime!``
"""
).lstrip(),
'\n'.join(output),
@@ -348,7 +348,7 @@
.. option:: --param <param>
- :default: Something computed at runtime
+ :default: ``Something computed at runtime``
A sample epilog.
"""
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/sphinx-click-4.3.0/tox.ini
new/sphinx-click-4.4.0/tox.ini
--- old/sphinx-click-4.3.0/tox.ini 2022-07-04 13:00:24.000000000 +0200
+++ new/sphinx-click-4.4.0/tox.ini 2022-12-06 14:00:28.000000000 +0100
@@ -1,16 +1,21 @@
[tox]
minversion = 2.0
-envlist = py{37,38,39}-click{7,8,8-async},py{310}-click{8,8-async},style,docs
+envlist =
py{37,38,39}-click{7,8,8-async},py{310,311}-click{8,8-async},style,docs
[testenv]
+setenv =
+ PYTHONDEVMODE = 1
+ PYTHONWARNINGS = all
+ PYTEST_ADDOPTS = {env:PYTEST_ADDOPTS:} --color yes
deps =
+ pytest
+ pytest-cov
coverage
click7: click>=7.0,<8.0
click8: click>=8.0,<9.0
click8-async: asyncclick>=8.0,<9.0
commands =
- coverage run --source={toxinidir}/sphinx_click -m unittest {posargs}
- coverage report
+ python -m pytest --cov {toxinidir}/sphinx_click {posargs}
pip_pre =
pre: true
