Rewrite testing docs and move from rst to myst (#2857)

General rewrite of testing docs:
    Add contents to the top.
    Added sub commands and context headings. Rewrote the other sections

Convert to myst:
    Should have done this in a separate PR because the diff is basically useless. Open lastest docs side by side with docs generated by PR. The changes to the text are pretty straight forward.
    Added dependencies so build will succeed.
    Ran rst2myst to convert. Worked pretty well with a few typos. Next time should use uvx install to install in own environment since its requirements are not up to date so it will downgrade your sphinx if you install it in the project environment.

Make dev environment nicer:
    Add sphinx-autobuild so you can run sphinx-autobuild -b html ./docs ./_build and docs changes will rebuild and update on save. I have been using it for several years and it is quite nice.

Author: Rowlando13

docs/api.rst

@@ -6,6 +6,10 @@ API
 This part of the documentation lists the full API reference of all public
 classes and functions.
 
+.. contents::
+   :depth: 1
+   :local:
+
 Decorators
 ----------
 
@@ -199,6 +203,8 @@ customizing Click's shell completion system.
 .. autofunction:: add_completion_class
 
 
+.. _testing:
+
 Testing
 -------
 

docs/conf.py

@@ -18,6 +18,7 @@
     "sphinx_tabs.tabs",
     "sphinxcontrib.log_cabinet",
     "pallets_sphinx_themes",
+    "myst_parser",
 ]
 autodoc_member_order = "bysource"
 autodoc_typehints = "description"

docs/testing.md

@@ -0,0 +1,198 @@
+# Testing Click Applications
+
+```{eval-rst}
+.. currentmodule:: click.testing
+```
+
+Click provides the {ref}`click.testing <testing>` module to help you invoke command line applications and check their behavior.
+
+These tools should only be used for testing since they change
+the entire interpreter state for simplicity. They are not thread-safe!
+
+The examples use [pytest](https://docs.pytest.org/en/stable/) style tests.
+
+```{contents}
+:depth: 1
+:local: true
+```
+
+## Basic Example
+
+The key pieces are:
+  - {class}`CliRunner` - used to invoke commands as command line scripts.
+  - {class}`Result` - returned from {meth}`CliRunner.invoke`. Captures output data, exit code, optional exception, and captures the output as bytes and binary data.
+
+```{code-block} python
+:caption: hello.py
+
+import click
+
+@click.command()
+@click.argument('name')
+def hello(name):
+   click.echo(f'Hello {name}!')
+```
+
+```{code-block} python
+:caption: test_hello.py
+
+from click.testing import CliRunner
+from hello import hello
+
+def test_hello_world():
+  runner = CliRunner()
+  result = runner.invoke(hello, ['Peter'])
+  assert result.exit_code == 0
+  assert result.output == 'Hello Peter!\n'
+```
+
+## Subcommands
+
+A subcommand name must be specified in the `args` parameter {meth}`CliRunner.invoke`:
+
+```{code-block} python
+:caption: sync.py
+
+import click
+
+@click.group()
+@click.option('--debug/--no-debug', default=False)
+def cli(debug):
+   click.echo(f"Debug mode is {'on' if debug else 'off'}")
+
+@cli.command()
+def sync():
+   click.echo('Syncing')
+```
+
+```{code-block} python
+:caption: test_sync.py
+
+from click.testing import CliRunner
+from sync import cli
+
+def test_sync():
+  runner = CliRunner()
+  result = runner.invoke(cli, ['--debug', 'sync'])
+  assert result.exit_code == 0
+  assert 'Debug mode is on' in result.output
+  assert 'Syncing' in result.output
+```
+
+## Context Settings
+
+Additional keyword arguments passed to {meth}`CliRunner.invoke` will be used to construct the initial {class}`Context object <click.Context>`.
+For example, setting a fixed terminal width equal to 60:
+
+```{code-block} python
+:caption: sync.py
+
+import click
+
+@click.group()
+def cli():
+   pass
+
+@cli.command()
+def sync():
+   click.echo('Syncing')
+```
+
+```{code-block} python
+:caption: test_sync.py
+
+from click.testing import CliRunner
+from sync import cli
+
+def test_sync():
+  runner = CliRunner()
+  result = runner.invoke(cli, ['sync'], terminal_width=60)
+  assert result.exit_code == 0
+  assert 'Debug mode is on' in result.output
+  assert 'Syncing' in result.output
+```
+
+## File System Isolation
+
+The {meth}`CliRunner.isolated_filesystem` context manager sets the current working directory to a new, empty folder.
+
+```{code-block} python
+:caption: cat.py
+
+import click
+
+@click.command()
+@click.argument('f', type=click.File())
+def cat(f):
+   click.echo(f.read())
+```
+
+```{code-block} python
+:caption: test_cat.py
+
+from click.testing import CliRunner
+from cat import cat
+
+def test_cat():
+   runner = CliRunner()
+   with runner.isolated_filesystem():
+      with open('hello.txt', 'w') as f:
+          f.write('Hello World!')
+
+      result = runner.invoke(cat, ['hello.txt'])
+      assert result.exit_code == 0
+      assert result.output == 'Hello World!\n'
+```
+
+Pass in a path to control where the temporary directory is created.
+In this case, the directory will not be removed by Click. Its useful
+to integrate with a framework like Pytest that manages temporary files.
+
+```{code-block} python
+:caption: test_cat.py
+
+from click.testing import CliRunner
+from cat import cat
+
+def test_cat_with_path_specified():
+   runner = CliRunner()
+   with runner.isolated_filesystem('~/test_folder'):
+      with open('hello.txt', 'w') as f:
+          f.write('Hello World!')
+
+      result = runner.invoke(cat, ['hello.txt'])
+      assert result.exit_code == 0
+      assert result.output == 'Hello World!\n'
+```
+
+## Input Streams
+
+The test wrapper can provide input data for the input stream (stdin). This is very useful for testing prompts.
+
+```{code-block} python
+:caption: prompt.py
+
+import click
+
+@click.command()
+@click.option('--foo', prompt=True)
+def prompt(foo):
+   click.echo(f"foo={foo}")
+```
+
+```{code-block} python
+:caption: test_prompt.py
+
+from click.testing import CliRunner
+from prompt import prompt
+
+def test_prompts():
+   runner = CliRunner()
+   result = runner.invoke(prompt, input='wau wau\n')
+   assert not result.exception
+   assert result.output == 'Foo: wau wau\nfoo=wau wau\n'
+```
+
+Prompts will be emulated so they write the input data to
+the output stream as well. If hidden input is expected then this
+does not happen.

docs/testing.rst

@@ -3,3 +3,4 @@
 -r typing.txt
 pre-commit
 tox
+sphinx-autobuild