diff --git a/CHANGES.rst b/CHANGES.rst index 4a2a938e08..377273f68b 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -1,6 +1,6 @@ .. currentmodule:: click -Version 8.4.dev +Version 8.4.1 ------------------ Unreleased diff --git a/docs/changes.rst b/docs/changes.md similarity index 50% rename from docs/changes.rst rename to docs/changes.md index 955deaf27b..a0e673f07e 100644 --- a/docs/changes.rst +++ b/docs/changes.md @@ -1,4 +1,5 @@ -Changes -======= +# Changes +```{eval-rst} .. include:: ../CHANGES.rst +``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000000..4549769c22 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,152 @@ +# + +```{image} _static/click-name.svg +:align: center +:height: 200px +``` + +Click is a Python package for creating beautiful command line interfaces +in a composable way with as little code as necessary. It's the "Command +Line Interface Creation Kit". It's highly configurable but comes with +sensible defaults out of the box. + +It aims to make the process of writing command line tools quick and fun +while also preventing any frustration caused by the inability to implement +an intended CLI API. + +Click in three points: + +- arbitrary nesting of commands +- automatic help page generation +- supports lazy loading of subcommands at runtime + +What does it look like? Here is an example of a simple Click program: + +```{eval-rst} +.. click:example:: + + import click + + @click.command() + @click.option('--count', default=1, help='Number of greetings.') + @click.option('--name', prompt='Your name', + help='The person to greet.') + def hello(count, name): + """Simple program that greets NAME for a total of COUNT times.""" + for x in range(count): + click.echo(f"Hello {name}!") + + if __name__ == '__main__': + hello() + + +And what it looks like when run: + + +.. click:run:: + + invoke(hello, ['--count=3'], prog_name='python hello.py', input='John\n') + + +It automatically generates nicely formatted help pages: + + +.. click:run:: + + invoke(hello, ['--help'], prog_name='python hello.py') +``` + +You can get the library directly from PyPI: + +``` +pip install click +``` + +# Documentation + +```{toctree} +:maxdepth: 2 + +faqs +``` + +## Tutorials + +```{toctree} +:maxdepth: 1 + +quickstart +virtualenv +``` + +## How to Guides + +```{toctree} +:maxdepth: 1 + +entry-points +setuptools +standalone-apps +upgrade-guides +support-multiple-versions +``` + +## Conceptual Guides + +```{toctree} +:maxdepth: 1 + +design-opinions +why +click-concepts +``` + +## General Reference + +```{toctree} +:maxdepth: 1 + +parameters +parameter-types +options +option-decorators +arguments +commands-and-groups +commands +documentation +prompts +handling-files +advanced +complex +extending-click +testing +utils +shell-completion +exceptions +command-line-reference +unicode-support +wincmd +``` + +## API Reference + +```{toctree} +:maxdepth: 2 + +api +``` + +# About Project + +- This documentation is structured according to [Diataxis](https://diataxis.fr/) and written with [MyST](https://myst-parser.readthedocs.io/en/latest/) +- [Version Policy](https://palletsprojects.com/versions) +- [Donate](https://palletsprojects.com/donate) + +```{toctree} +:maxdepth: 1 + +contributing +contrib +license +changes +``` diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index c496e59c5f..0000000000 --- a/docs/index.rst +++ /dev/null @@ -1,145 +0,0 @@ -.. rst-class:: hide-header - -Welcome to Click -================ - -.. image:: _static/click-name.svg - :align: center - :height: 200px - -Click is a Python package for creating beautiful command line interfaces -in a composable way with as little code as necessary. It's the "Command -Line Interface Creation Kit". It's highly configurable but comes with -sensible defaults out of the box. - -It aims to make the process of writing command line tools quick and fun -while also preventing any frustration caused by the inability to implement -an intended CLI API. - -Click in three points: - -- arbitrary nesting of commands -- automatic help page generation -- supports lazy loading of subcommands at runtime - -What does it look like? Here is an example of a simple Click program: - -.. click:example:: - - import click - - @click.command() - @click.option('--count', default=1, help='Number of greetings.') - @click.option('--name', prompt='Your name', - help='The person to greet.') - def hello(count, name): - """Simple program that greets NAME for a total of COUNT times.""" - for x in range(count): - click.echo(f"Hello {name}!") - - if __name__ == '__main__': - hello() - -And what it looks like when run: - -.. click:run:: - - invoke(hello, ['--count=3'], prog_name='python hello.py', input='John\n') - -It automatically generates nicely formatted help pages: - -.. click:run:: - - invoke(hello, ['--help'], prog_name='python hello.py') - -You can get the library directly from PyPI:: - - pip install click - -Documentation -============== - -.. toctree:: - :maxdepth: 2 - - faqs - -Tutorials ------------- -.. toctree:: - :maxdepth: 1 - - quickstart - virtualenv - -How to Guides ---------------- -.. toctree:: - :maxdepth: 1 - - entry-points - setuptools - standalone-apps - upgrade-guides - support-multiple-versions - -Conceptual Guides -------------------- -.. toctree:: - :maxdepth: 1 - - design-opinions - why - click-concepts - -General Reference --------------------- - -.. toctree:: - :maxdepth: 1 - - parameters - parameter-types - options - option-decorators - arguments - commands-and-groups - commands - documentation - prompts - handling-files - advanced - complex - extending-click - testing - utils - shell-completion - exceptions - command-line-reference - unicode-support - wincmd - -API Reference -------------------- - -.. toctree:: - :maxdepth: 2 - - api - -About Project -=============== - -* This documentation is structured according to `Diataxis `_ and written with `MyST `_ - -* `Version Policy `_ - -* `Donate `_ - -.. toctree:: - :maxdepth: 1 - - contributing - contrib - license - changes diff --git a/pyproject.toml b/pyproject.toml index d4d40e2e12..833209b67a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "click" -version = "8.4.dev" +version = "8.4.1.dev" description = "Composable command line interface toolkit" readme = "README.md" license = "BSD-3-Clause" diff --git a/uv.lock b/uv.lock index 9b2d6d0fa9..5f7aca8d4e 100644 --- a/uv.lock +++ b/uv.lock @@ -173,7 +173,7 @@ wheels = [ [[package]] name = "click" -version = "8.4.dev0" +version = "8.4.1.dev0" source = { editable = "." } dependencies = [ { name = "colorama", marker = "sys_platform == 'win32'" },