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 <dmuel...@suse.com> + +- 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 <m...@mortis.eu> Hugo Osvaldo Barrera <h...@barrera.io> James Ennis <james.en...@codethink.com> +Jared Dillard <jared.dillard+git...@gmail.com> JeremyB <jeremybillhei...@gmail.com> Jiri Kuncar <jiri.kun...@gmail.com> José Sánchez-Gallego <galle...@uw.edu> +Kevin Deldycke <ke...@deldycke.com> Lev Gorodetskiy <github@droserasprout.space> Maarten ter Huurne <maar...@treewalker.org> Miro HronÄok <m...@hroncok.cz> 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 + + +@click.command() +@click.option('--param', envvar='PARAM', help='A sample option') +@click.option('--another', metavar='[FOO]', help='Another option') +@click.option( + '--choice', + help='A sample option with choices', + type=click.Choice(['Option1', 'Option2']), +) +@click.option( + '--numeric-choice', + metavar='<choice>', + help='A sample option with numeric choices', + type=click.Choice([1, 2, 3]), +) +@click.option( + '--flag', + is_flag=True, + help='A boolean flag', +) +@click.argument('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 + + +@click.group() +@click.option( + '--debug', + default=False, + is_flag=True, + help="Output more information about what's going on.", +) +def cli(): + """A sample command group.""" + pass + + +@cli.command() +@click.option('--param', envvar='PARAM', help='A sample option') +@click.option('--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'] + + +@pytest.fixture +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 + + +@click.group() +def greet(): + """A sample command group.""" + pass + + +@greet.command() +@click.argument('user', envvar='USER') +def hello(user): + """Greet a user.""" + click.echo('Hello %s' % user) + + +@greet.command() +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 + + +@click.group() +def greet(): + """A sample command group.""" + pass + + +@greet.command() +@click.argument('user', envvar='USER') +def hello(user): + """Greet a user.""" + click.echo('Hello %s' % user) + + +@greet.command() +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