diff --git a/docs/images/cli_help/cz___help.svg b/docs/images/cli_help/cz___help.svg new file mode 100644 index 0000000000..07b23d558f --- /dev/null +++ b/docs/images/cli_help/cz___help.svg @@ -0,0 +1,198 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + $ cz --help +usage: cz [-h][--debug][-n NAME][-nr NO_RAISE] +{init,commit,c,ls,example,info,schema,bump,changelog,ch,check,version} +... + +Commitizen is a cli tool to generate conventional commits. +For more information about the topic go to https://conventionalcommits.org/ + +options: +  -h, --help            show this help message and exit +  --debug               use debug mode +  -n NAME, --name NAME  use the given commitizen (default: +                        cz_conventional_commits) +  -nr NO_RAISE, --no-raise NO_RAISE +                        comma separated error codes that won't rise error, +                        e.g: cz -nr 1,2,3 bump. See codes at +https://commitizen- +                        tools.github.io/commitizen/exit_codes/ + +commands: +{init,commit,c,ls,example,info,schema,bump,changelog,ch,check,version} +    init                init commitizen configuration +    commit (c)          create new commit +    ls                  show available commitizens +    example             show commit example +    info                show information about the cz +    schema              show commit schema +    bump                bump semantic version based on the git log +    changelog (ch)      generate changelog (note that it will overwrite +                        existing file) +    check               validates that a commit message matches the commitizen +                        schema +    version             get the version of the installed commitizen or the +                        current project (default: installed commitizen) + + + + + diff --git a/docs/images/cli_help/cz_bump___help.svg b/docs/images/cli_help/cz_bump___help.svg new file mode 100644 index 0000000000..18d402f16e --- /dev/null +++ b/docs/images/cli_help/cz_bump___help.svg @@ -0,0 +1,373 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + $ 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}] +[--increment-mode {linear,exact}][--check-consistency] +[--annotated-tag] +[--annotated-tag-message ANNOTATED_TAG_MESSAGE][--gpg-sign] +[--changelog-to-stdout][--git-output-to-stderr][--retry] +[--major-version-zero][--template TEMPLATE][--extra EXTRA] +[--file-name FILE_NAME][--prerelease-offset PRERELEASE_OFFSET] +[--version-scheme {semver,pep440}] +[--version-type {semver,pep440}] +[--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 {linear,exact} +                        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 +  --annotated-tag-message ANNOTATED_TAG_MESSAGE, -atm ANNOTATED_TAG_MESSAGE +                        create annotated tag message +  --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 +  --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') +  --file-name FILE_NAME +                        file name of changelog (default: 'CHANGELOG.md') +  --prerelease-offset PRERELEASE_OFFSET +                        start pre-releases with this offset +  --version-scheme {semver,pep440} +                        choose version scheme +  --version-type {semver,pep440} +                        Deprecated, use --version-scheme +  --build-metadata BUILD_METADATA +                        Add additional build-metadata to the version-number + + + + + diff --git a/docs/images/cli_help/cz_changelog___help.svg b/docs/images/cli_help/cz_changelog___help.svg new file mode 100644 index 0000000000..4f236ea467 --- /dev/null +++ b/docs/images/cli_help/cz_changelog___help.svg @@ -0,0 +1,217 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + $ cz changelog --help +usage: cz changelog [-h][--dry-run][--file-name FILE_NAME] +[--unreleased-version UNRELEASED_VERSION][--incremental] +[--start-rev START_REV][--merge-prerelease] +[--version-scheme {pep440,semver}] +[--export-template EXPORT_TEMPLATE][--template TEMPLATE] +[--extra EXTRA] + + +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) + +options: +  -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 +  --version-scheme {pep440,semver} +                        choose version scheme +  --export-template EXPORT_TEMPLATE +                        Export the changelog template into this file instead +                        of rendering it +  --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') + + + + + diff --git a/docs/images/cli_help/cz_check___help.svg b/docs/images/cli_help/cz_check___help.svg new file mode 100644 index 0000000000..82dab7282e --- /dev/null +++ b/docs/images/cli_help/cz_check___help.svg @@ -0,0 +1,149 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + $ cz check --help +usage: cz check [-h] +[--commit-msg-file COMMIT_MSG_FILE | --rev-range REV_RANGE | -m  +MESSAGE] +[--allow-abort][--allowed-prefixes [ALLOWED_PREFIXES ...]] + +options: +  -h, --help            show this help message and exit +  --commit-msg-file COMMIT_MSG_FILE +                        ask for the name of the temporal file that contains +                        the commit message. Using it in a git hook script: +MSG_FILE=$1 +  --rev-range REV_RANGE +                        a range of git rev to check. e.g, master..HEAD +  -m MESSAGE, --message MESSAGE +                        commit message that needs to be checked +  --allow-abort         allow empty commit messages, which typically abort a +                        commit +  --allowed-prefixes [ALLOWED_PREFIXES ...] +                        allowed commit message prefixes. If the message starts +                        by one of these prefixes, the message won't be checked +                        against the regex + + + + + diff --git a/docs/images/cli_help/cz_commit___help.svg b/docs/images/cli_help/cz_commit___help.svg new file mode 100644 index 0000000000..e29f55607d --- /dev/null +++ b/docs/images/cli_help/cz_commit___help.svg @@ -0,0 +1,123 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + $ cz commit --help +usage: cz commit [-h][--retry][--no-retry][--dry-run] +[--write-message-to-file FILE_PATH][-s][-a] + +options: +  -h, --help            show this help message and exit +  --retry               retry last commit +  --no-retry            skip retry if retry_after_failure is set to true +  --dry-run             show output to stdout, no commit, no modified files +  --write-message-to-file FILE_PATH +                        write message to file before committing (can be +                        combined with --dry-run) +  -s, --signoff         sign off the commit +  -a, --all             Tell the command to automatically stage files that +                        have been modified and deleted, but new files you have +                        not told Git about are not affected. + + + + + diff --git a/docs/images/cli_help/cz_example___help.svg b/docs/images/cli_help/cz_example___help.svg new file mode 100644 index 0000000000..a3fee0064a --- /dev/null +++ b/docs/images/cli_help/cz_example___help.svg @@ -0,0 +1,79 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + $ cz example --help +usage: cz example [-h] + +options: +  -h, --help  show this help message and exit + + + + + diff --git a/docs/images/cli_help/cz_info___help.svg b/docs/images/cli_help/cz_info___help.svg new file mode 100644 index 0000000000..02c2f313df --- /dev/null +++ b/docs/images/cli_help/cz_info___help.svg @@ -0,0 +1,79 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + $ cz info --help +usage: cz info [-h] + +options: +  -h, --help  show this help message and exit + + + + + diff --git a/docs/images/cli_help/cz_init___help.svg b/docs/images/cli_help/cz_init___help.svg new file mode 100644 index 0000000000..b296b79d76 --- /dev/null +++ b/docs/images/cli_help/cz_init___help.svg @@ -0,0 +1,79 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + $ cz init --help +usage: cz init [-h] + +options: +  -h, --help  show this help message and exit + + + + + diff --git a/docs/images/cli_help/cz_ls___help.svg b/docs/images/cli_help/cz_ls___help.svg new file mode 100644 index 0000000000..7e95d4c8dc --- /dev/null +++ b/docs/images/cli_help/cz_ls___help.svg @@ -0,0 +1,79 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + $ cz ls --help +usage: cz ls [-h] + +options: +  -h, --help  show this help message and exit + + + + + diff --git a/docs/images/cli_help/cz_schema___help.svg b/docs/images/cli_help/cz_schema___help.svg new file mode 100644 index 0000000000..201778bdfd --- /dev/null +++ b/docs/images/cli_help/cz_schema___help.svg @@ -0,0 +1,79 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + $ cz schema --help +usage: cz schema [-h] + +options: +  -h, --help  show this help message and exit + + + + + diff --git a/docs/images/cli_help/cz_version___help.svg b/docs/images/cli_help/cz_version___help.svg new file mode 100644 index 0000000000..0a7dc85397 --- /dev/null +++ b/docs/images/cli_help/cz_version___help.svg @@ -0,0 +1,99 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + $ cz version --help +usage: cz version [-h][-r | -p | -c | -v] + +options: +  -h, --help        show this help message and exit +  -r, --report      get system information for reporting bugs +  -p, --project     get the version of the current project +  -c, --commitizen  get the version of the installed commitizen +  -v, --verbose     get the version of both the installed commitizen and the +                    current project + + + + + diff --git a/poetry.lock b/poetry.lock index 21dfdb2d79..34de953d88 100644 --- a/poetry.lock +++ b/poetry.lock @@ -617,6 +617,30 @@ importlib-metadata = {version = ">=4.4", markers = "python_version < \"3.10\""} docs = ["mdx-gh-links (>=0.2)", "mkdocs (>=1.5)", "mkdocs-gen-files", "mkdocs-literate-nav", "mkdocs-nature (>=0.6)", "mkdocs-section-index", "mkdocstrings[python]"] testing = ["coverage", "pyyaml"] +[[package]] +name = "markdown-it-py" +version = "3.0.0" +description = "Python port of markdown-it. Markdown parsing, done right!" +optional = false +python-versions = ">=3.8" +files = [ + {file = "markdown-it-py-3.0.0.tar.gz", hash = "sha256:e3f60a94fa066dc52ec76661e37c851cb232d92f9886b15cb560aaada2df8feb"}, + {file = "markdown_it_py-3.0.0-py3-none-any.whl", hash = "sha256:355216845c60bd96232cd8d8c40e8f9765cc86f46880e43a8fd22dc1a1a8cab1"}, +] + +[package.dependencies] +mdurl = ">=0.1,<1.0" + +[package.extras] +benchmarking = ["psutil", "pytest", "pytest-benchmark"] +code-style = ["pre-commit (>=3.0,<4.0)"] +compare = ["commonmark (>=0.9,<1.0)", "markdown (>=3.4,<4.0)", "mistletoe (>=1.0,<2.0)", "mistune (>=2.0,<3.0)", "panflute (>=2.3,<3.0)"] +linkify = ["linkify-it-py (>=1,<3)"] +plugins = ["mdit-py-plugins"] +profiling = ["gprof2dot"] +rtd = ["jupyter_sphinx", "mdit-py-plugins", "myst-parser", "pyyaml", "sphinx", "sphinx-copybutton", "sphinx-design", "sphinx_book_theme"] +testing = ["coverage", "pytest", "pytest-cov", "pytest-regressions"] + [[package]] name = "markupsafe" version = "2.1.3" @@ -700,6 +724,17 @@ files = [ [package.dependencies] traitlets = "*" +[[package]] +name = "mdurl" +version = "0.1.2" +description = "Markdown URL utilities" +optional = false +python-versions = ">=3.7" +files = [ + {file = "mdurl-0.1.2-py3-none-any.whl", hash = "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8"}, + {file = "mdurl-0.1.2.tar.gz", hash = "sha256:bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba"}, +] + [[package]] name = "mergedeep" version = "1.3.4" @@ -1405,6 +1440,25 @@ urllib3 = ">=1.21.1,<3" socks = ["PySocks (>=1.5.6,!=1.5.7)"] use-chardet-on-py3 = ["chardet (>=3.0.2,<6)"] +[[package]] +name = "rich" +version = "13.7.1" +description = "Render rich text, tables, progress bars, syntax highlighting, markdown and more to the terminal" +optional = false +python-versions = ">=3.7.0" +files = [ + {file = "rich-13.7.1-py3-none-any.whl", hash = "sha256:4edbae314f59eb482f54e9e30bf00d33350aaa94f4bfcd4e9e3110e64d0d7222"}, + {file = "rich-13.7.1.tar.gz", hash = "sha256:9be308cb1fe2f1f57d67ce99e95af38a1e2bc71ad9813b0e247cf7ffbcc3a432"}, +] + +[package.dependencies] +markdown-it-py = ">=2.2.0" +pygments = ">=2.13.0,<3.0.0" +typing-extensions = {version = ">=4.0.0,<5.0", markers = "python_version < \"3.9\""} + +[package.extras] +jupyter = ["ipywidgets (>=7.5.1,<9)"] + [[package]] name = "ruff" version = "0.3.4" @@ -1766,4 +1820,4 @@ testing = ["big-O", "jaraco.functools", "jaraco.itertools", "more-itertools", "p [metadata] lock-version = "2.0" python-versions = ">=3.8" -content-hash = "614f9b1db867d5b7f954c318309b0e7b18951ed7be6d8016af79a08b8c2c7a89" +content-hash = "5cd809db4e9dc8005ab2295ca7d182435021752953a7b1552bb81912b54df791" diff --git a/pyproject.toml b/pyproject.toml index d1e03c436e..3410a50aba 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -73,6 +73,7 @@ mkdocs-material = "^9.1.6" deprecated = "^1.2.13" types-deprecated = "^1.2.9.2" types-python-dateutil = "^2.8.19.13" +rich = "^13.7.1" [tool.poetry.scripts] diff --git a/scripts/gen_cli_help_screenshots.py b/scripts/gen_cli_help_screenshots.py new file mode 100644 index 0000000000..0706612391 --- /dev/null +++ b/scripts/gen_cli_help_screenshots.py @@ -0,0 +1,42 @@ +import os +import subprocess +from pathlib import Path + +from rich.console import Console + +from commitizen.cli import data + +project_root = Path(__file__).parent.parent.absolute() +images_root = project_root / Path("docs") / Path("images") / Path("cli_help") + + +def gen_cli_help_screenshots() -> None: + """Generate the screenshot for help message on each cli command and save them as svg files.""" + if not os.path.exists(images_root): + os.makedirs(images_root) + print(f"Created {images_root}") + + help_cmds = _list_help_cmds() + for cmd in help_cmds: + file_name = f"{cmd.replace(' ', '_').replace('-', '_')}.svg" + _export_cmd_as_svg(cmd, f"{images_root}/{file_name}") + + +def _list_help_cmds() -> list[str]: + cmds = [f"{data['prog']} --help"] + [ + f"{data['prog']} {sub_c['name'] if isinstance(sub_c['name'], str) else sub_c['name'][0]} --help" + for sub_c in data["subcommands"]["commands"] + ] + + return cmds + + +def _export_cmd_as_svg(cmd: str, file_name: str) -> None: + stdout = subprocess.run(cmd, shell=True, capture_output=True).stdout.decode("utf-8") + console = Console(record=True, width=80) + console.print(f"$ {cmd}\n{stdout}") + console.save_svg(file_name, title="") + + +if __name__ == "__main__": + gen_cli_help_screenshots()