docs: misc consistency & tidy

Author: casperdcl

.pre-commit-config.yaml

@@ -25,7 +25,7 @@ repos:
     args: [-i]
     entry: TODO
     types: [text]
-    exclude: ^(.pre-commit-config.yaml|.github/workflows/test.yml)$
+    exclude: ^.pre-commit-config.yaml$
   - id: pytest
     name: pytest
     language: python

README.rst

@@ -29,7 +29,7 @@ Features
   - `click <https://pypi.org/project/click>`_
 
 - ``<arguments>``, ``--options`` and ``sub commands``
-- Choices (``--say={hello,goodbye}```)
+- Choices (``--say={hello,goodbye}``)
 - Paths (``--file={*.y*ml,*.toml}``, ``--dir=*/``)
 - Dynamic shell commands (``--branch=$(git branch)``)
 

docs/index.md

@@ -92,17 +92,17 @@ follow the OS-specific instructions below.
 
 ## FAQs
 
-Not working?
-
 - Ensure that `shtab` and the application you're trying to complete are both accessible from your environment.
-- Ensure that `prog` is set:
-    - if using [`options.entry_points.console_scripts=MY_PROG=...`](https://setuptools.pypa.io/en/latest/userguide/entry_point.html), then ensure the main parser's `prog` matches `argparse.ArgumentParser(prog="MY_PROG")` or override it using `shtab MY_PROG.get_main_parser --prog=MY_PROG`.
-    - if executing a script file `./MY_PROG.py` (with a [shebang](<https://en.wikipedia.org/wiki/Shebang_(Unix)>) `#!/usr/bin/env python`) directly, then use `argparse.ArgumentParser(prog="MY_PROG.py")` or override it using `shtab MY_PROG.get_main_parser --prog=MY_PROG.py`.
-- Any argument with `help=argparse.SUPPRESS` is skipped.
+- Ensure that `prog` matches the executable name:
+    - if using [`project.scripts.MY-PROG=...`](https://setuptools.pypa.io/en/latest/userguide/entry_point.html), then
+        - set the main parser's name (`argparse.ArgumentParser(prog="MY-PROG")`, `argopt(prog="MY-PROG")`, `click.group("MY-PROG")`, `click.command("MY-PROG")`, etc)
+        - or override it using `shtab MY_PROG.get_main_parser --prog=MY-PROG`
+    - if executing a script file `./MY_PROG.py` (with a [shebang](<https://en.wikipedia.org/wiki/Shebang_(Unix)>) `#!/usr/bin/env python`) directly, then use `prog="MY_PROG.py"`
+- Any suppressed argument (`help=argparse.SUPPRESS`, click `hidden=True`/`deprecated=True`) is skipped.
 - Default completion (when no choices are specified) is disabled. Enable it explicitly via e.g. `parser.add_argument('positional').complete = shtab.FILE`.
 - Some shells (e.g. `zsh`, `fish`) print information during tab completion:
-    - subparser `description` takes precedence over `help`.
-    - argument `metavar` takes precedence over `dest`.
+    - subparser `description` takes precedence over `help`
+    - argument `metavar` takes precedence over `dest`
 - [Ask a general question on StackOverflow](https://stackoverflow.com/questions/tagged/shtab).
 - [Report bugs and open feature requests on GitHub][issues].
 

docs/use.md

@@ -103,6 +103,8 @@ Below are various examples of enabling `shtab`'s own tab completion scripts.
       | sudo tee /usr/share/fish/vendor_completions.d/shtab.fish
     ```
 
+### argparse
+
 Any existing `argparse`-based scripts should be supported with minimal effort.
 For example, starting with this existing code:
 
@@ -111,7 +113,7 @@ For example, starting with this existing code:
 import argparse
 
 def get_main_parser():
-    parser = argparse.ArgumentParser(prog="MY_PROG", ...)
+    parser = argparse.ArgumentParser(prog="MY-PROG", ...)
     parser.add_argument(...)
     parser.add_subparsers(...)
     ...
@@ -123,39 +125,39 @@ if __name__ == '__main__':
     ...
 ```
 
-Assuming this code example is installed in `MY_PROG.command.main`, simply run:
+Assuming this code example is installed in `MY_PROG.cli`, simply run:
 
 === "bash"
 
     ```sh
-    shtab --shell=bash -u MY_PROG.command.main.get_main_parser \
-      | sudo tee /etc/bash_completion.d/MY_PROG
+    shtab --shell=bash -u MY_PROG.cli.get_main_parser \
+      | sudo tee /etc/bash_completion.d/MY-PROG
     ```
 
 === "zsh"
 
     ```sh
-    shtab --shell=zsh -u MY_PROG.command.main.get_main_parser \
-      | sudo tee /usr/local/share/zsh/site-functions/_MY_PROG
+    shtab --shell=zsh -u MY_PROG.cli.get_main_parser \
+      | sudo tee /usr/local/share/zsh/site-functions/_MY-PROG
     ```
 
 === "tcsh"
 
     ```sh
-    shtab --shell=tcsh -u MY_PROG.command.main.get_main_parser \
-      | sudo tee /etc/profile.d/MY_PROG.completion.csh
+    shtab --shell=tcsh -u MY_PROG.cli.get_main_parser \
+      | sudo tee /etc/profile.d/MY-PROG.completion.csh
     ```
 
 === "fish"
 
     ```sh
-    shtab --shell=fish -u MY_PROG.command.main.get_main_parser \
-      | sudo tee /usr/share/fish/vendor_completions.d/MY_PROG.fish
+    shtab --shell=fish -u MY_PROG.cli.get_main_parser \
+      | sudo tee /usr/share/fish/vendor_completions.d/MY-PROG.fish
     ```
 
 ### click
 
-Speedup `click`'s completions (and get support for more shell types) by changing from e.g. `_MY_PROG_COMPLETE=bash_source my-prog` to `shtab my_prog.cli.cli --prog my-prog -s bash`
+Speedup `click`'s completions (and get support for more shell types) by changing from e.g. `_MY_PROG_COMPLETE=bash_source MY-PROG` to `shtab MY_PROG.cli.main --prog MY-PROG -s bash`
 
 ## Library Usage
 
@@ -229,7 +231,7 @@ Add direct support to scripts for a little more configurability:
         main()
     ```
 
-=== "click"
+=== "click.command"
 
     ```{.py title="click_process.py" linenums="1" hl_lines="5"}
     #!/usr/bin/env python
@@ -249,7 +251,7 @@ Add direct support to scripts for a little more configurability:
         process()
     ```
 
-=== "click (group/subcommand)"
+=== "click.group"
 
     ```{.py title="click_subcommand.py" linenums="1" hl_lines="17"}
     #!/usr/bin/env python