From 1f6b70fc10d7ba9a564e814e973672df466fc24d Mon Sep 17 00:00:00 2001 From: Wei Lee Date: Thu, 25 Apr 2024 23:28:20 +0800 Subject: [PATCH 1/2] docs: fix missing links, reorganize documentation and replace command help messages with images --- docs/README.md | 2 +- docs/{ => commands}/bump.md | 66 ++----------------- docs/{ => commands}/changelog.md | 34 ++-------- docs/{ => commands}/check.md | 6 +- docs/{ => commands}/commit.md | 7 +- docs/{ => commands}/init.md | 8 ++- docs/config.md | 22 +++---- docs/contributing.md | 2 +- docs/customization.md | 4 +- docs/getting_started.md | 8 +-- docs/tutorials/auto_prepare_commit_message.md | 2 +- docs/tutorials/gitlab_ci.md | 2 +- mkdocs.yml | 10 +-- 13 files changed, 53 insertions(+), 120 deletions(-) rename docs/{ => commands}/bump.md (83%) rename docs/{ => commands}/changelog.md (76%) rename docs/{ => commands}/check.md (89%) rename docs/{ => commands}/commit.md (91%) rename docs/{ => commands}/init.md (86%) diff --git a/docs/README.md b/docs/README.md index 8c7dc51e48..b4fa13eb2c 100644 --- 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/bump.md b/docs/commands/bump.md similarity index 83% rename from docs/bump.md rename to docs/commands/bump.md index 6dad38219e..5f5590e885 100644 --- a/docs/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/changelog.md b/docs/commands/changelog.md similarity index 76% rename from docs/changelog.md rename to docs/commands/changelog.md index 029882c12b..cbf22b15a7 100644 --- a/docs/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/check.md b/docs/commands/check.md similarity index 89% rename from docs/check.md rename to docs/commands/check.md index 1cd42c74a9..c31fd085ee 100644 --- a/docs/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/commit.md b/docs/commands/commit.md similarity index 91% rename from docs/commit.md rename to docs/commands/commit.md index 2c1b94f63e..7760a2b88e 100644 --- a/docs/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/init.md b/docs/commands/init.md similarity index 86% rename from docs/init.md rename to docs/commands/init.md index 778a79f529..01e1db6be8 100644 --- a/docs/init.md +++ b/docs/commands/init.md @@ -1,4 +1,8 @@ -![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 @@ -6,6 +10,8 @@ To start using commitizen, the recommended approach is to run 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 index 7ef8644fa2..398c045339 100644 --- 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 index 77ee1f44fe..a41843d753 100644 --- 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 index 1fd1826e03..e8f233fce1 100644 --- 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 index e826a5e424..7ceba2bb65 100644 --- 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 index 80a1b211d7..3011142679 100644 --- 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 index 7b6e2032df..de1336b675 100644 --- 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 index 1f76605153..f80e427981 100644 --- 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: From bbcbf03f79a68cbf8ad66bf5c17a6df0e763bd87 Mon Sep 17 00:00:00 2001 From: Wei Lee Date: Thu, 25 Apr 2024 23:44:51 +0800 Subject: [PATCH 2/2] docs: initial documentation for undocumented commands --- docs/commands/example.md | 5 +++++ docs/commands/info.md | 5 +++++ docs/commands/ls.md | 3 +++ docs/commands/schema.md | 5 +++++ docs/commands/version.md | 5 +++++ mkdocs.yml | 15 ++++++++++----- 6 files changed, 33 insertions(+), 5 deletions(-) create mode 100644 docs/commands/example.md create mode 100644 docs/commands/info.md create mode 100644 docs/commands/ls.md create mode 100644 docs/commands/schema.md create mode 100644 docs/commands/version.md diff --git a/docs/commands/example.md b/docs/commands/example.md new file mode 100644 index 0000000000..8243453916 --- /dev/null +++ b/docs/commands/example.md @@ -0,0 +1,5 @@ +Show commit example + +## Usage + +![cz example --help](../images/cli_help/cz_example___help.svg) diff --git a/docs/commands/info.md b/docs/commands/info.md new file mode 100644 index 0000000000..5f816ba88d --- /dev/null +++ b/docs/commands/info.md @@ -0,0 +1,5 @@ +Show information about the cz + +## Usage + +![cz info --help](../images/cli_help/cz_info___help.svg) diff --git a/docs/commands/ls.md b/docs/commands/ls.md new file mode 100644 index 0000000000..f255ca5444 --- /dev/null +++ b/docs/commands/ls.md @@ -0,0 +1,3 @@ +## Usage + +![cz ls --help](../images/cli_help/cz_ls___help.svg) diff --git a/docs/commands/schema.md b/docs/commands/schema.md new file mode 100644 index 0000000000..bd6fa85195 --- /dev/null +++ b/docs/commands/schema.md @@ -0,0 +1,5 @@ +Show commit schema + +## Usage + +![cz schema --help](../images/cli_help/cz_schema___help.svg) diff --git a/docs/commands/version.md b/docs/commands/version.md new file mode 100644 index 0000000000..9a8176b45f --- /dev/null +++ b/docs/commands/version.md @@ -0,0 +1,5 @@ +Get the version of the installed commitizen or the current project (default: installed commitizen) + +## Usage + +![cz version --help](../images/cli_help/cz_version___help.svg) diff --git a/mkdocs.yml b/mkdocs.yml index f80e427981..a0fb57fde2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -33,11 +33,16 @@ nav: - Introduction: "README.md" - Getting Started: "getting_started.md" - Commands: - - Init: "commands/init.md" - - Commit: "commands/commit.md" - - Bump: "commands/bump.md" - - Check: "commands/check.md" - - Changelog: "commands/changelog.md" + - init: "commands/init.md" + - commit: "commands/commit.md" + - bump: "commands/bump.md" + - check: "commands/check.md" + - changelog: "commands/changelog.md" + - example: "commands/example.md" + - info: "commands/info.md" + - ls: "commands/ls.md" + - schema: "commands/schema.md" + - version: "commands/version.md" - Configuration: "config.md" - Customization: "customization.md" - Tutorials: