docs: fix missing links, reorganize documentation and replace command help messages with images

Lee-W · Lee-W · commit 1f6b70fc10d7 · 2024-05-06T23:56:57.000+08:00
diff --git a/docs/README.md b/docs/README.md
@@ -32,7 +32,7 @@ descriptive commits.
 ### Features
 
 - Command-line utility to create commits with your rules. Defaults: [Conventional commits][conventional_commits]
-- Bump version automatically using [semantic versioning][semver] based on the commits. [Read More](./bump.md)
+- Bump version automatically using [semantic versioning][semver] based on the commits. [Read More](./commands/bump.md)
 - Generate a changelog using [Keep a changelog][keepchangelog]
 - Update your project's version files automatically
 - Display information about your commit rules (commands: schema, example, info)
diff --git a/docs/commands/bump.md b/docs/commands/bump.md
@@ -1,4 +1,4 @@
-![Bump version](images/bump.gif)
+![Bump version](../images/bump.gif)
 
 ## About
 
@@ -50,60 +50,8 @@ Some examples of pep440:
 
 ## Usage
 
-```bash
-$ cz bump --help
-usage: cz bump [-h] [--dry-run] [--files-only] [--local-version] [--changelog] [--no-verify] [--yes] [--tag-format TAG_FORMAT]
-               [--bump-message BUMP_MESSAGE] [--prerelease {alpha,beta,rc}] [--devrelease DEVRELEASE] [--increment {MAJOR,MINOR,PATCH}]
-               [--check-consistency] [--annotated-tag] [--gpg-sign] [--changelog-to-stdout] [--git-output-to-stderr] [--retry] [--major-version-zero]
-               [--prerelease-offset PRERELEASE_OFFSET] [--version-scheme {pep440,semver,semver2}] [--version-type {pep440,semver,semver2}] [--build-metadata BUILD_METADATA]
-               [MANUAL_VERSION]
-
-positional arguments:
-  MANUAL_VERSION        bump to the given version (e.g: 1.5.3)
-
-options:
-  -h, --help            show this help message and exit
-  --dry-run             show output to stdout, no commit, no modified files
-  --files-only          bump version in the files from the config
-  --local-version       bump only the local version portion
-  --changelog, -ch      generate the changelog for the newest version
-  --no-verify           this option bypasses the pre-commit and commit-msg hooks
-  --yes                 accept automatically questions done
-  --tag-format TAG_FORMAT
-                        the format used to tag the commit and read it, use it in existing projects, wrap around simple quotes
-  --bump-message BUMP_MESSAGE
-                        template used to create the release commit, useful when working with CI
-  --prerelease {alpha,beta,rc}, -pr {alpha,beta,rc}
-                        choose type of prerelease
-  --devrelease DEVRELEASE, -d DEVRELEASE
-                        specify non-negative integer for dev. release
-  --increment {MAJOR,MINOR,PATCH}
-                        manually specify the desired increment
-  --increment-mode
-                        set the method by which the new version is chosen. 'linear' (default) guesses the next version based
-                        on typical linear version progression, such that bumping of a pre-release with lower precedence than
-                        the current pre-release phase maintains the current phase of higher precedence. 'exact' applies the
-                        changes that have been specified (or determined from the commit log) without interpretation, such that
-                        the increment and pre-release are always honored
-  --check-consistency, -cc
-                        check consistency among versions defined in commitizen configuration and version_files
-  --annotated-tag, -at  create annotated tag instead of lightweight one
-  --gpg-sign, -s        sign tag instead of lightweight one
-  --changelog-to-stdout
-                        Output changelog to the stdout
-  --git-output-to-stderr
-                        Redirect git output to stderr
-  --retry               retry commit if it fails the 1st time
-  --major-version-zero  keep major version at zero, even for breaking changes
-  --prerelease-offset PRERELEASE_OFFSET
-                        start pre-releases with this offset
-  --version-scheme {pep440,semver,semver2}
-                        choose version scheme
-  --version-type {pep440,semver,semver2}
-                        Deprecated, use --version-scheme
-  --build-metadata {BUILD_METADATA}
-                        additional metadata in the version string
-```
+![cz bump --help](../images/cli_help/cz_bump___help.svg)
+
 
 ### `--files-only`
 
@@ -306,7 +254,7 @@ Yes, you shouldn't have any issues.
 ### `--template`
 
 Provides your own changelog jinja template.
-See [the template customization section](customization.md#customizing-the-changelog-template)
+See [the template customization section](../customization.md#customizing-the-changelog-template)
 
 ### `--extra`
 
@@ -316,7 +264,7 @@ Provides your own changelog extra variables by using the `extras` settings or th
 cz bump --changelog --extra key=value -e short="quoted value"
 ```
 
-See [the template customization section](customization.md#customizing-the-changelog-template).
+See [the template customization section](../customization.md#customizing-the-changelog-template).
 
 ### `--build-metadata`
 
@@ -388,7 +336,7 @@ cz --no-raise 3,4,5
 
 ### Longer way
 
-Check the list of [exit_codes](./exit_codes.md) and understand which one you have
+Check the list of [exit_codes](../exit_codes.md) and understand which one you have
 to skip and why.
 
 Remember to document somewhere this, because you'll forget.
@@ -637,7 +585,7 @@ version_scheme = "semver"
 
 ## Custom bump
 
-Read the [customizing section](./customization.md).
+Read the [customizing section](../customization.md).
 
 [pep440]: https://www.python.org/dev/peps/pep-0440/
 [semver]: https://semver.org/
diff --git a/docs/commands/changelog.md b/docs/commands/changelog.md
@@ -11,33 +11,7 @@ update_changelog_on_bump = true
 
 ## Usage
 
-```bash
-$ cz changelog --help
-usage: cz changelog [-h] [--dry-run] [--file-name FILE_NAME] [--unreleased-version UNRELEASED_VERSION] [--incremental] [--start-rev START_REV]
-                    [--template TEMPLATE] [--extra EXTRA]
-                    [rev_range]
-
-positional arguments:
-  rev_range             generates changelog for the given version (e.g: 1.5.3) or version range (e.g: 1.5.3..1.7.9)
-
-optional arguments:
-  -h, --help            show this help message and exit
-  --dry-run             show changelog to stdout
-  --file-name FILE_NAME
-                        file name of changelog (default: 'CHANGELOG.md')
-  --unreleased-version UNRELEASED_VERSION
-                        set the value for the new version (use the tag value), instead of using unreleased
-  --incremental         generates changelog from last created version, useful if the changelog has been manually modified
-  --start-rev START_REV
-                        start rev of the changelog. If not set, it will generate changelog from the start
-  --merge-prerelease
-                        collect all changes from prereleases into next non-prerelease. If not set, it will include prereleases in the changelog
-                        start rev of the changelog.If not set, it will generate changelog from the start
-  --template TEMPLATE, -t TEMPLATE
-                        changelog template file name (relative to the current working directory)
-  --extra EXTRA, -e EXTRA
-                        a changelog extra variable (in the form 'key=value')
-```
+![cz changelog --help](../images/cli_help/cz_changelog___help.svg)
 
 ### Examples
 
@@ -195,7 +169,7 @@ changelog_merge_prerelease = true
 ### `template`
 
 Provides your own changelog jinja template by using the `template` settings or the `--template` parameter.
-See [the template customization section](customization.md#customizing-the-changelog-template)
+See [the template customization section](../customization.md#customizing-the-changelog-template)
 
 ### `extras`
 
@@ -205,7 +179,7 @@ Provides your own changelog extra variables by using the `extras` settings or th
 cz changelog --extra key=value -e short="quoted value"
 ```
 
-See [the template customization section](customization.md#customizing-the-changelog-template)
+See [the template customization section](../customization.md#customizing-the-changelog-template)
 
 ## Hooks
 
@@ -218,4 +192,4 @@ Read more about hooks in the [customization page][customization]
 
 [keepachangelog]: https://keepachangelog.com/
 [semver]: https://semver.org/
-[customization]: ./customization.md
+[customization]: ../customization.md
diff --git a/docs/commands/check.md b/docs/commands/check.md
@@ -5,10 +5,12 @@
 This feature checks whether the commit message follows the given committing rules. And comment in git message will be ignored.
 
 If you want to setup an automatic check before every git commit, please refer to
-[Automatically check message before commit](./tutorials/auto_check.md).
+[Automatically check message before commit](../tutorials/auto_check.md).
 
 ## Usage
 
+![cz check --help](../images/cli_help/cz_check___help.svg)
+
 There are three mutually exclusive ways to use `cz check`:
 
 - with `--rev-range` to check a range of pre-existing commits
@@ -54,7 +56,7 @@ $ cz check --commit-msg-file COMMIT_MSG_FILE
 ```
 
 In this option, COMMIT_MSG_FILE is the path of the temporal file that contains the commit message.
-This argument can be useful when cooperating with git hook, please check [Automatically check message before commit](./tutorials/auto_check.md) for more information about how to use this argument with git hook.
+This argument can be useful when cooperating with git hook, please check [Automatically check message before commit](../tutorials/auto_check.md) for more information about how to use this argument with git hook.
 
 ### Allow Abort
 
diff --git a/docs/commands/commit.md b/docs/commands/commit.md
@@ -1,4 +1,4 @@
-![Using commitizen cli](images/demo.gif)
+![Using commitizen cli](../images/demo.gif)
 
 ## About
 
@@ -7,13 +7,16 @@ In your terminal run `cz commit` or the shortcut `cz c` to generate a guided git
 You can run `cz commit --write-message-to-file COMMIT_MSG_FILE` to additionally save the
 generated message to a file. This can be combined with the `--dry-run` flag to only
 write the message to a file and not modify files and create a commit. A possible use
-case for this is to [automatically prepare a commit message](./tutorials/auto_prepare_commit_message.md).
+case for this is to [automatically prepare a commit message](../tutorials/auto_prepare_commit_message.md).
 
 
 !!! note
     To maintain platform compatibility, the `commit` command disable ANSI escaping in its output.
     In particular pre-commit hooks coloring will be deactivated as discussed in [commitizen-tools/commitizen#417](https://github.com/commitizen-tools/commitizen/issues/417).
 
+## Usage
+
+![cz commit --help](../images/cli_help/cz_commit___help.svg)
 
 ### git options
 
diff --git a/docs/commands/init.md b/docs/commands/init.md
@@ -1,11 +1,17 @@
-![Bump version](images/init.gif)
+## Usage
+
+![cz init --help](../images/cli_help/cz_init___help.svg)
+
+## Example
 
 To start using commitizen, the recommended approach is to run
 
 ```sh
 cz init
 ```
 
+![init](../images/init.gif)
+
 This command will ask you for information about the project and will
 configure the selected file type (`pyproject.toml`, `.cz.toml`, etc.).
 
diff --git a/docs/config.md b/docs/config.md
@@ -384,17 +384,17 @@ setup(
 )
 ```
 
-[version_files]: bump.md#version_files
-[tag_format]: bump.md#tag_format
-[bump_message]: bump.md#bump_message
-[major-version-zero]: bump.md#-major-version-zero
-[prerelease-offset]: bump.md#-prerelease_offset
-[retry_after_failure]: commit.md#retry
-[allow_abort]: check.md#allow-abort
-[version-scheme]: bump.md#version-scheme
-[pre_bump_hooks]: bump.md#pre_bump_hooks
-[post_bump_hooks]: bump.md#post_bump_hooks
-[allowed_prefixes]: check.md#allowed-prefixes
+[version_files]: commands/bump.md#version_files
+[tag_format]: commands/bump.md#tag_format
+[bump_message]: commands/bump.md#bump_message
+[major-version-zero]: commands/bump.md#-major-version-zero
+[prerelease-offset]: commands/bump.md#-prerelease_offset
+[retry_after_failure]: commands/commit.md#retry
+[allow_abort]: commands/check.md#allow-abort
+[version-scheme]: commands/bump.md#version-scheme
+[pre_bump_hooks]: commands/bump.md#pre_bump_hooks
+[post_bump_hooks]: commands/bump.md#post_bump_hooks
+[allowed_prefixes]: commands/check.md#allowed-prefixes
 [additional-features]: https://github.com/tmbo/questionary#additional-features
 [customization]: customization.md
 [shortcuts]: customization.md#shortcut-keys
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -105,4 +105,4 @@ flowchart TD
 ```
 
 
-[conventional-commmits]: https://www.conventionalcommits.org/
+[conventional-commits]: https://www.conventionalcommits.org/
diff --git a/docs/customization.md b/docs/customization.md
@@ -193,7 +193,7 @@ The basic steps are:
 3. Create a python package using `setup.py`, `poetry`, etc
 4. Expose the class as a `commitizen.plugin` entrypoint
 
-Check an [example](convcomms) on how to configure `BaseCommitizen`.
+Check an [example][convcomms] on how to configure `BaseCommitizen`.
 
 You can also automate the steps above through [cookiecutter](https://cookiecutter.readthedocs.io/en/1.7.0/).
 
@@ -372,7 +372,7 @@ class StrangeCommitizen(BaseCommitizen):
         return full_changelog
 ```
 
-[changelog-des]: ./changelog.md#description
+[changelog-des]: ./commands/changelog.md#description
 
 ### Raise Customize Exception
 
diff --git a/docs/getting_started.md b/docs/getting_started.md
@@ -27,10 +27,10 @@ cz bump
 This command will bump your project's version, and it will create a tag.
 
 Because of the setting `update_changelog_on_bump`, bump will also create the **changelog**.
-You can also [update files](./bump.md#version_files).
-You can configure the [version scheme](./bump.md#version_scheme) and [version provider](./config.md#version-providers).
+You can also [update files](./commands/bump.md#version_files).
+You can configure the [version scheme](./commands/bump.md#version_scheme) and [version provider](./config.md#version-providers).
 
-There are many more options available, please read the docs for the [bump command](./bump.md).
+There are many more options available, please read the docs for the [bump command](./commands/bump.md).
 
 ### Committing
 
@@ -116,4 +116,4 @@ Note that pre-commit discourages using `master` as a revision, and the above com
 pre-commit autoupdate
 ```
 
-Read more about the `check` command [here](check.md).
+Read more about the `check` command [here](commands/check.md).
diff --git a/docs/tutorials/auto_prepare_commit_message.md b/docs/tutorials/auto_prepare_commit_message.md
@@ -7,7 +7,7 @@ squash) so that the complete git history adheres to the commit message conventio
 without ever having to call `cz commit`.
 
 To automatically prepare a commit message prior to committing, you can
-use a [prepare-commit-msg Git hook](prepare-commit-msg-docs):
+use a [prepare-commit-msg Git hook][prepare-commit-msg-docs]:
 
 > This hook is invoked by git-commit right after preparing the
 > default log message, and before the editor is started.
diff --git a/docs/tutorials/gitlab_ci.md b/docs/tutorials/gitlab_ci.md
@@ -10,7 +10,7 @@ _Goal_: Bump a new version every time that a change occurs on the `master` branc
 2. A developer creates a merge request (MR) against `master` branch
 3. When the `MR` is merged into master, the 2 stages of the CI are executed
 4. For simplification, we store the software version in a file called `VERSION`. You can use any file that you want as `commitizen` supports it.
-5. The commit message executed automatically by the `CI` must include `[skip-ci]` in the message; otherwise, the process will generate a loop. You can define the message structure in [commitizen](../bump.md) as well.
+5. The commit message executed automatically by the `CI` must include `[skip-ci]` in the message; otherwise, the process will generate a loop. You can define the message structure in [commitizen](../commands/bump.md) as well.
 
 ### Gitlab Configuration
 
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -33,11 +33,11 @@ nav:
   - Introduction: "README.md"
   - Getting Started: "getting_started.md"
   - Commands:
-      - Init: "init.md"
-      - Commit: "commit.md"
-      - Bump: "bump.md"
-      - Check: "check.md"
-      - Changelog: "changelog.md"
+      - Init: "commands/init.md"
+      - Commit: "commands/commit.md"
+      - Bump: "commands/bump.md"
+      - Check: "commands/check.md"
+      - Changelog: "commands/changelog.md"
   - Configuration: "config.md"
   - Customization: "customization.md"
   - Tutorials:

Original file line number	Diff line number	Diff line change
`@@ -105,4 +105,4 @@ flowchart TD`
`105`	`105`	```
`106`	`106`
`107`	`107`
`108`		`-[conventional-commmits]: https://www.conventionalcommits.org/`
	`108`	`+[conventional-commits]: https://www.conventionalcommits.org/`