wip

Author: bearomorphism

docs/commands/changelog.md

@@ -14,33 +14,25 @@ This command will generate a changelog following the committing rules establishe
 
 ![cz changelog --help](../images/cli_help/cz_changelog___help.svg)
 
-### Examples
-
-#### Generate full changelog
+## Examples
 
 ```bash
+# Generate full changelog
 cz changelog
-```
 
-```bash
+# or use the alias
 cz ch
-```
 
-#### Get the changelog for the given version
-
-```bash
+# Get the changelog for the given version
 cz changelog 0.3.0 --dry-run
-```
-
-#### Get the changelog for the given version range
 
-```bash
+# Get the changelog for the given version range
 cz changelog 0.3.0..0.4.0 --dry-run
 ```
 
 ## Constrains
 
-changelog generation is constrained only to **markdown** files.
+Changelog generation is constrained only to **markdown** files.
 
 ## Description
 
@@ -73,51 +65,31 @@ and the following variables are expected:
 
 - **required**: is the only one required to be parsed by the regex
 
-## Configuration
-
-### `unreleased_version`
-
-There is usually a chicken and egg situation when automatically
-bumping the version and creating the changelog.
-If you bump the version first, you have no changelog, you have to
-create it later, and it won't be included in
-the release of the created version.
-
-If you create the changelog before bumping the version, then you
-usually don't have the latest tag, and the _Unreleased_ title appears.
+## Command line options
 
-By introducing `unreleased_version` you can prevent this situation.
+### `--extras`
 
-Before bumping you can run:
+Provides your own changelog extra variables by using the `extras` settings or the `--extra/-e` parameter.
 
 ```bash
-cz changelog --unreleased-version="v1.0.0"
+cz changelog --extra key=value -e short="quoted value"
 ```
 
-Remember to use the tag instead of the raw version number
-
-For example if the format of your tag includes a `v` (`v1.0.0`), then you should use that,
-if your tag is the same as the raw version, then ignore this.
-
-Alternatively you can directly bump the version and create the changelog by doing
-
-```bash
-cz bump --changelog
-```
+See [the template customization section](../customization.md#customizing-the-changelog-template)
 
-### `file-name`
+### `--file-name`
 
-This value can be updated in the `toml` file with the key `changelog_file` under `tools.commitizen`
+This value can be updated in the configuration file with the key `changelog_file` under `tools.commitizen`
 
 Specify the name of the output file, remember that changelog only works with Markdown.
 
 ```bash
 cz changelog --file-name="CHANGES.md"
 ```
 
-### `incremental`
+### `--incremental`
 
-This flag can be set in the `toml` file with the key `changelog_incremental` under `tools.commitizen`
+This flag can be set in the configuration file with the key `changelog_incremental` under `tools.commitizen`
 
 Benefits:
 
@@ -135,9 +107,9 @@ cz changelog --incremental
 changelog_incremental = true
 ```
 
-### `start-rev`
+### `--start-rev`
 
-This value can be set in the `toml` file with the key `changelog_start_rev` under `tools.commitizen`
+This value can be set in the configuration file with the key `changelog_start_rev` under `tools.commitizen`
 
 Start from a given git rev to generate the changelog. Commits before that rev will not be considered. This is especially useful for long-running projects adopting conventional commits, where old commit messages might fail to be parsed for changelog generation.
 
@@ -151,9 +123,9 @@ cz changelog --start-rev="v0.2.0"
 changelog_start_rev = "v0.2.0"
 ```
 
-### merge-prerelease
+### `--merge-prerelease`
 
-This flag can be set in the `toml` file with the key `changelog_merge_prerelease` under `tools.commitizen`
+This flag can be set in the configuration file with the key `changelog_merge_prerelease` under `tools.commitizen`
 
 Collects changes from prereleases into the next non-prerelease. This means that if you have a prerelease version, and then a normal release, the changelog will show the prerelease changes as part of the changes of the normal release. If not set, it will include prereleases in the changelog.
 
@@ -167,20 +139,40 @@ cz changelog --merge-prerelease
 changelog_merge_prerelease = true
 ```
 
-### `template`
+### `--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)
 
-### `extras`
+### `--unreleased-version`
 
-Provides your own changelog extra variables by using the `extras` settings or the `--extra/-e` parameter.
+There is usually a chicken and egg situation when automatically
+bumping the version and creating the changelog.
+If you bump the version first, you have no changelog, you have to
+create it later, and it won't be included in
+the release of the created version.
+
+If you create the changelog before bumping the version, then you
+usually don't have the latest tag, and the _Unreleased_ title appears.
+
+By introducing `--unreleased-version` you can prevent this situation.
+
+Before bumping you can run:
 
 ```bash
-cz changelog --extra key=value -e short="quoted value"
+cz changelog --unreleased-version="v1.0.0"
 ```
 
-See [the template customization section](../customization.md#customizing-the-changelog-template)
+Remember to use the tag instead of the raw version number
+
+For example if the format of your tag includes a `v` (`v1.0.0`), then you should use that,
+if your tag is the same as the raw version, then ignore this.
+
+Alternatively you can directly bump the version and create the changelog by doing
+
+```bash
+cz bump --changelog
+```
 
 ## Hooks
 

docs/config/changelog.md

@@ -1,55 +1,8 @@
 # Changelog Options
 
 <!-- When adding a new option, please keep the alphabetical order. -->
+<!-- If there is a new configuration option that doesn't have a corresponding command line option, please add it here. -->
 
-## `changelog_file`
+As for now, each of the options that is used by `cz changelog` command can correlate to a command line option.
 
-- Type: `str`
-- Default: `CHANGELOG.md`
-
-Filename of exported changelog
-
-## `changelog_format`
-
-- Type: `str`
-- Default: `None`
-
-Format used to parse and generate the changelog. If not specified, resolved from [`changelog_file`](#changelog_file).
-
-## `changelog_incremental`
-
-- Type: `bool`
-- Default: `False`
-
-Update changelog with the missing versions. This is good if you don't want to replace previous versions in the file.
-
-!!! note
-    When doing `cz bump --changelog`, this is automatically set to `True`.
-
-## `changelog_merge_prerelease`
-
-- Type: `bool`
-- Default: `False`
-
-Collect all changes of prerelease versions into the next non-prerelease version when creating the changelog.
-
-## `changelog_start_rev`
-
-- Type: `str`
-- Default: `None`
-
-Start from a given git rev to generate the changelog.
-
-## `template`
-
-- Type: `str`
-- Default: `None` (provided by plugin)
-
-Provide custom changelog jinja template path relative to the current working directory. See [template customization](../customization.md#customizing-the-changelog-template) for more details.
-
-## `extras`
-
-- Type: `dict[str, Any]`
-- Default: `{}`
-
-Provide extra variables to the changelog template. See [template customization](../customization.md#customizing-the-changelog-template) for more details.
+See [changelog command line options](../commands/changelog.md#command-line-options) for more details.

docs/customization.md

@@ -524,6 +524,6 @@ by:
 - defining them in your configuration with the [`extras` settings][extras-config]
 - providing them on the command line with the `--extra/-e` parameter to `bump` and `changelog` commands
 
-[template-config]: config/changelog.md#template
-[extras-config]: config/changelog.md#extras
-[changelog-des]: ./commands/changelog.md#description
+[template-config]: commands/changelog.md#-template
+[extras-config]: commands/changelog.md#-extras
+[changelog-des]: commands/changelog.md#description