Add extensive documentation for the 'show' subcommand

This commit adds extensive documentation for the `show` subcommand in the program's reference. It also includes smaller updates and corrections to other parts of the documentation. An in-depth example usage of `show` is added both to the dedicated `show.md` file and in the function's docstring.

bumpversion/cli.py

@@ -338,7 +338,19 @@ def bump(
     help="Increment the version part and add `new_version` to the configuration.",
 )
 def show(args: List[str], config_file: Optional[str], format_: str, increment: Optional[str]) -> None:
-    """Show current configuration information."""
+    """
+    Show current configuration information.
+
+    ARGS may contain one or more configuration attributes. For example:
+
+    - `bump-my-version show current_version`
+
+    - `bump-my-version show files.0.filename`
+
+    - `bump-my-version show scm_info.branch_name`
+
+    - `bump-my-version show current_version scm_info.distance_to_latest_tag`
+    """
     found_config_file = find_config_file(config_file)
     config = get_configuration(found_config_file)
 

docs/reference/cli.md

@@ -1,3 +1,5 @@
+# CLI Reference
+
 ::: mkdocs-click
     :module: bumpversion.cli
     :command: cli

docs/reference/configuration.md

@@ -68,7 +68,7 @@ Bump-my-version's default behavior is to abort if the working directory has unco
 
 Whether to create a commit using git or Mercurial.
 
-If you have pre-commit hooks, you might also want to add an option to [`commit_args`](configuration.md#commit-args) to disable your pre-commit hooks. For Git use `--no-verify` and use `--config hooks.pre-commit=` for Mercurial.
+If you have pre-commit hooks, you might also want to add an option to [`commit_args`](configuration.md#commit_args) to disable your pre-commit hooks. For Git use `--no-verify` and use `--config hooks.pre-commit=` for Mercurial.
 
 ### commit_args
 
@@ -339,7 +339,7 @@ If `True`, sign the created tag, when [`tag`](configuration.md#tag) is `True`.
     environment var
     : `BUMPVERSION_TAG`
 
-If `True`, create a tag after committing the changes. The tag is named using the [`tag_name`](configuration.md#tag-name) option. 
+If `True`, create a tag after committing the changes. The tag is named using the [`tag_name`](configuration.md#tag_name) option. 
 
 If you are using `git`, don't forget to `git-push` with the `--tags` flag when you are done.
 
@@ -533,7 +533,7 @@ When this value is set to `True`, the part is always incremented when the versio
     type
     : string
 
-The `calver_format` is a string that specifies the format of the version part. It is used to determine the next value when bumping the version. The format is a string that uses the placeholders defined in the [CalVer reference](calver_reference.md#calver-format).
+The `calver_format` is a string that specifies the format of the version part. It is used to determine the next value when bumping the version. The format is a string that uses the placeholders defined in the [CalVer reference](calver_reference.md#calver_format).
 
 ### Examples
 

docs/reference/index.md

@@ -1,8 +1,9 @@
 # Reference
 
-
+- [Subcommands](subcommands/index.md)
 - [Command-line interface](cli.md)
 - [Configuration](configuration.md)
+- [Calendar versioning reference](calver_reference.md)
 - [Formatting context](formatting-context.md)
 - [Version parts](version-parts.md)
 - [Search and replace configuration](search-and-replace-config.md)

docs/reference/subcommands/index.md

@@ -0,0 +1,9 @@
+# Subcommand reference
+
+Bump-my-version uses subcommands to focus its functionality.
+
+- `bump` triggers the version incrementing workflow
+- `replace` replaces the version in files without triggering a version increment.
+- `sample-config` helps new users configure bumpy-my-version by printing a sample configuration file.
+- `show` provides access to current configuration information.
+- `show-bump` helps developers understand the current versioning convention by showing the possible versions resulting from the `bump` subcommand.

docs/reference/subcommands/show.md

@@ -0,0 +1,53 @@
+# The show subcommand
+
+The main purpose of the `show` subcommand is to provide access to configuration data via scripts.
+
+## Basic use
+
+The configuration object is a `dict` containing nested data structures. The arguments and options of this command relate to extracting data from the configuration object and presenting the extracted data. 
+
+## Specifying the output data
+
+The positional arguments determine the data shown. If nothing or `all` is passed, the entire configuration is shown.
+
+Positional arguments are specified using a format like [Django variable resolution](https://docs.djangoproject.com/en/5.0/ref/templates/language/#variables).
+
+Examples:
+
+- `a.b` specifies the "b" key in the nested dictionaries: `{"a": {"b": "value"}}`
+- `a.3` specifies the 4th item (the first is 0) of the list at key "a": `{"a": ["no", "nay", "nyet", "value"]}`
+
+## Specifying the output format
+
+If only one positional argument is passed, the default format only shows its value. If no positional arguments, several positional arguments, or `all` is passed, the output from [`pprint.pprint`](https://docs.python.org/3.12/library/pprint.html#pprint.pprint) is shown.
+
+This makes getting the current version easy:
+
+```console
+$ bump-my-version show current_version
+1.0.1
+```
+
+You can request the output be formatted as YAML or JSON:
+
+```console
+$ bump-my-version show --format yaml current_version
+current_version: "1.0.1"
+$ bump-my-version show --format json current_version
+{
+  "current_version": "1.0.1"
+}
+```
+
+## Including the incremented version before bumping
+
+Your workflow might want to know the new version before you actually do the bumping. The `--increment` or `-i` option accepts a version part to bump and adds a `new_version` key into the configuration.
+
+```console
+$ bump-my-version --increment patch show
+1.0.2
+$ bump-my-version --increment minor show
+1.1.0
+$ bump-my-version --increment major show
+2.0.0
+```