Rewrite first half of options docs (#2825)

Co-authored-by: Andreas Backx <[email protected]>

docs/api.rst

@@ -113,6 +113,7 @@ Context
     :members:
     :member-order: bysource
 
+.. _click-api-types:
 
 Types
 -----

docs/documentation.rst

@@ -108,6 +108,42 @@ Or more explicitly:
 
     invoke(touch, args=['--help'])
 
+
+Showing Defaults
+---------------------------
+To control the appearance of defaults pass ``show_default``.
+
+.. click:example::
+
+    @click.command()
+    @click.option('--n', default=1, show_default=False, help='number of dots')
+    def dots(n):
+        click.echo('.' * n)
+
+.. click:run::
+
+    invoke(dots, args=['--help'])
+
+For single option boolean flags, the default remains hidden if the default value is False even if show default is true.
+
+.. click:example::
+
+    @click.command()
+    @click.option('--n', default=1, show_default=True)
+    @click.option("--gr", is_flag=True, show_default=True, default=False, help="Greet the world.")
+    @click.option("--br", is_flag=True, show_default=True, default=True, help="Add a thematic break")
+    def dots(n, gr, br):
+        if gr:
+            click.echo('Hello world!')
+        click.echo('.' * n)
+        if br:
+            click.echo('-' * n)
+
+.. click:run::
+
+   invoke(dots, args=['--help'])
+
+
 Click's Wrapping Behavior
 ----------------------------
 Click's default wrapping ignores single new lines and rewraps the text based on the width of the terminal, to a maximum of 80 characters. In the example notice how the second grouping of three lines is rewrapped into a single paragraph.

docs/index.rst

@@ -72,8 +72,10 @@ usage patterns.
    virtualenv
    setuptools
    parameters
-   arguments
+   parameter-types
    options
+   option-decorators
+   arguments
    commands
    documentation
    prompts

docs/option-decorators.rst

@@ -0,0 +1,80 @@
+Options Shortcut Decorators
+===========================
+
+.. currentmodule:: click
+
+For convenience commonly used combinations of options arguments are available as their own decorators.
+
+.. contents::
+    :depth: 2
+    :local:
+
+Password Option
+------------------
+
+Click supports hidden prompts and asking for confirmation.  This is
+useful for password input:
+
+.. click:example::
+
+    import codecs
+
+    @click.command()
+    @click.option(
+        "--password", prompt=True, hide_input=True,
+        confirmation_prompt=True
+    )
+    def encode(password):
+        click.echo(f"encoded: {codecs.encode(password, 'rot13')}")
+
+.. click:run::
+
+    invoke(encode, input=['secret', 'secret'])
+
+Because this combination of parameters is quite common, this can also be
+replaced with the :func:`password_option` decorator:
+
+.. code-block:: python
+
+    @click.command()
+    @click.password_option()
+    def encrypt(password):
+        click.echo(f"encoded: to {codecs.encode(password, 'rot13')}")
+
+Confirmation Option
+--------------------
+
+For dangerous operations, it's very useful to be able to ask a user for
+confirmation.  This can be done by adding a boolean ``--yes`` flag and
+asking for confirmation if the user did not provide it and to fail in a
+callback:
+
+.. click:example::
+
+    def abort_if_false(ctx, param, value):
+        if not value:
+            ctx.abort()
+
+    @click.command()
+    @click.option('--yes', is_flag=True, callback=abort_if_false,
+                  expose_value=False,
+                  prompt='Are you sure you want to drop the db?')
+    def dropdb():
+        click.echo('Dropped all tables!')
+
+And what it looks like on the command line:
+
+.. click:run::
+
+    invoke(dropdb, input=['n'])
+    invoke(dropdb, args=['--yes'])
+
+Because this combination of parameters is quite common, this can also be
+replaced with the :func:`confirmation_option` decorator:
+
+.. click:example::
+
+    @click.command()
+    @click.confirmation_option(prompt='Are you sure you want to drop the db?')
+    def dropdb():
+        click.echo('Dropped all tables!')