Updated more documentation

Makefile

@@ -1,29 +1,9 @@
-.PHONY: release-dev release-patch release-minor release-major help docs pubdocs do-release
+.PHONY: help docs pubdocs update-requires
 .DEFAULT_GOAL := help
 
-RELEASE_KIND := patch
-BRANCH_NAME := $(shell echo $$(git rev-parse --abbrev-ref HEAD))
-SHORT_BRANCH_NAME := $(shell echo $(BRANCH_NAME) | cut -c 1-20)
-PRIMARY_BRANCH_NAME := master
-BUMPVERSION_OPTS :=
-EDIT_CHANGELOG := $(shell if [[ -n $$EDITOR ]] ; then echo "$$EDITOR CHANGELOG.md" ; else echo "true" ; fi)
-
 help:
 	@grep '^[a-zA-Z]' $(MAKEFILE_LIST) | sort | awk -F ':.*?## ' 'NF==2 {printf "\033[36m  %-25s\033[0m %s\n", $$1, $$2}'
 
-release-dev: RELEASE_KIND := dev
-release-dev: do-release  ## Release a new development version: 1.1.1 -> 1.1.1+branchname-1
-
-release-patch: RELEASE_KIND := patch
-release-patch: do-release  ## Release a new patch version: 1.1.1 -> 1.1.2
-
-release-minor: RELEASE_KIND := minor
-release-minor: do-release  ## Release a new minor version: 1.1.1 -> 1.2.0
-
-release-major: RELEASE_KIND := major
-release-major: do-release  ## Release a new major version: 1.1.1 -> 2.0.0
-
-release-version: get-version do-release  ## Release a specific version: release-version 1.2.3
 
 docs: ## generate Sphinx HTML documentation, including API docs
 	mkdir -p docs
@@ -40,33 +20,3 @@ update-requires:  ## Update the requirements.txt file
 	pip-compile --extra=test --output-file=requirements/test.txt pyproject.toml
 	pip-compile --extra=docs --output-file=requirements/docs.txt pyproject.toml
 	pip-compile --extra=dev --extra=docs --extra=test --output-file=requirements/dev.txt pyproject.toml
-
-#
-# Helper targets. Not meant to use directly
-#
-
-do-release:
-	@if [[ "$(BRANCH_NAME)" == "$(PRIMARY_BRANCH_NAME)" ]]; then \
-		if [[ "$(RELEASE_KIND)" == "dev" ]]; then \
-			echo "Error! Can't bump $(RELEASE_KIND) while on the $(PRIMARY_BRANCH_NAME) branch."; \
-			exit; \
-		fi; \
-	elif [[ "$(RELEASE_KIND)" != "dev" ]]; then \
-		echo "Error! Must be on the $(PRIMARY_BRANCH_NAME) branch to bump $(RELEASE_KIND)."; \
-		exit; \
-	fi; \
-	git fetch -p --all; \
-	generate-changelog; \
-	$(call EDIT_CHANGELOG); \
-	./tools/gen-codeowners.sh $(SOURCE_DIR); \
-	git add CODEOWNERS; \
-	export BRANCH_NAME=$(SHORT_BRANCH_NAME);bumpversion $(BUMPVERSION_OPTS) $(RELEASE_KIND) --allow-dirty; \
-	git push origin $(BRANCH_NAME); \
-	git push --tags;
-
-get-version:  # Sets the value after release-version to the VERSION
-	$(eval VERSION := $(filter-out release-version,$(MAKECMDGOALS)))
-	$(eval BUMPVERSION_OPTS := --new-version=$(VERSION))
-
-%: # NO-OP for unrecognized rules
-	@:

README.md

@@ -18,23 +18,24 @@
 
 ## Overview
 
-Version-bump your software with a single command!
+Bump My Version's purpose is to:
 
-A small command line tool to simplify releasing software by updating all version strings in your source code by the correct increment and optionally commit and tag the changes.
+- Work as a part of an automated build system
+- Manage project versioning through the project's development life cycle
+    - Incrementing version numbers
+    - serializing version numbers
+    - parsing version numbers
+- Modify project files as part of the project's development life cycle
+- Work with the project's source control system
+    - Committing changes
+    - Tagging releases
+    - Reading version numbers from tags
 
-* version formats are highly configurable
-* works without any source code manager, but happily reads tag information from and writes
-  commits and tags to Git and Mercurial if available
-* just handles text files, so it's not specific to any programming language
-* supports Python 3.8+ and PyPy3.
 
 ## Future Direction
 
-- Make it easier to get the current version
 - Switch having both the version part and files to change as arguments on the command line.
-- Make the version part argument _truly_ optional when `--new-version` is specified
 - Allow for multiple tags, including one that moves for having a `v2` that always points to the latest version of version 2. [For example](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md#recommendations)
-- Better UI with [Rich](https://rich.readthedocs.io/en/stable/index.html)
 
 ## Installation
 

docsrc/_static/css/custom.css

@@ -35,3 +35,8 @@ dl.field-list > dd {
   margin-left: 0;
   margin-bottom: 0;
 }
+
+figure {
+  padding-bottom: .75rem;
+  padding-top: .5rem;
+}

docsrc/conf.py

@@ -23,7 +23,6 @@
     "myst_parser",
     "autodoc2",
     "sphinx.ext.viewcode",
-    "sphinx.ext.autosummary",
     "sphinx.ext.intersphinx",
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.napoleon",
@@ -40,8 +39,10 @@
 autodoc2_render_plugin = "myst"
 autodoc2_output_dir = "reference"
 autodoc2_index_template = None
-
-autosummary_generate = True
+autodoc2_docstring_parser_regexes = [
+    # this will render all docstrings as Markdown
+    (r".*", "myst"),
+]
 
 napoleon_attr_annotations = True
 napoleon_include_special_with_doc = True

docsrc/explanation/index.md

@@ -1,4 +1,8 @@
 # Explanation
 
 ```{toctree}
+---
+titlesonly: true
+---
+mental-model
 ```

docsrc/explanation/mental-model.md

@@ -0,0 +1,101 @@
+# The mental model used by bump-my-version
+
+## Overview
+
+There are four main concepts in bump-my-version:
+
+1. Configuration
+2. Version handling
+3. File changing
+4. Source control management interface
+
+## Configuration
+
+The predecessor to bump-my-version, [bumpversion](https://github.com/peritus/bumpversion), was designed to have the configuration file optional. All configuration values could be specified on the command line. This only worked in the simplest of version schemes.
+
+bump-my-version is designed to have a configuration file. The configuration file is required to specify the version scheme. The configuration file is also used to specify the files to change and how to change them.
+
+## Version handling
+
+bump-my-version abstracts the version handling into a few concepts:
+
+A **version spec** defines all the possible _version component specs_ of a version and how they work together.
+
+A **version component spec** defines how a single part of a _version spec,_ such as `major`, `minor`, or `patch`, works. It defines the types of values, how to increment the component, and how to reset it.
+
+A **version parser** is a regular expression used in several ways. It's named capture groups define the possible components in a version spec and the order in which they appear. It is also used to parse a version string into a mapping of version component name to value.
+
+A **version** is the concrete representation of a _version spec._ It is a mapping of version component names to _version components._ 
+
+A **version component** is the concrete representation of a _version component spec._ It is a _version component spec_ with a specific value.
+
+A **version serialization format** is a list of format strings used to serialize a _version_ into a string.
+
+### How a version spec is generated
+
+:::{figure-md} fig-version-spec
+![How a version spec is generated](../_static/creating-a-version-spec.svg)
+
+How a configuration file is used to generate a version spec.
+:::
+
+The most important part of the configuration file is the _version parser._ It defines the structure of the _version spec._ 
+
+
+If the configuration file contains a _version component spec_ that matches a named capture group in the _version parser,_ then that _version component spec_ is used in the _version spec._ The yellow and green named capture groups in the diagram demonstrate this.
+
+If the configuration file does not contain a _version component spec_ that matches a named capture group in the _version parser,_ then a default _version component spec_ is used. The blue named capture group in the diagram demonstrates this.
+
+The _component dependency_ graph is used to determine the order in which the _version components_ are incremented and reset. For example in the diagram, the `patch` component depends on the `minor` component which depends on the `major` component. Therefore, when the `major` component is incremented, the `minor` component is reset, which cascades to the `patch` component. 
+
+### How a version is generated
+
+:::{figure-md} fig-version
+![How a version is generated](../_static/creating-a-version.svg)
+
+How a version spec is used to generate a version.
+:::
+
+The _version spec_ has a `create_version` method that takes a mapping of version component names to values. 
+
+Each _version component spec_ has a `create_component` method that takes a value. The `create_version` method calls the `create_component` method for each _version component spec_ in the _version spec_ with the value from the mapping.
+
+The `create_component` assembles its own _version spec_ with the _version components_ to create a _version._
+
+### How a version is serialized
+
+**Optional value rule.** _Version component specs_ can define an optional value. For example, numeric components have `0` as an optional value. Optional values may be omitted from the serialization as long as all dependent components also have optional values.
+
+**Required value rule.** _Version component specs_ is required if its value or the value of any of its dependent components is not optional.
+
+A valid serialization is one that contains all the components in the _version spec_ that are required based on the _required value rule._
+
+An invalid serialization is one that does not contain all the components in the _version spec_ that are required based on the _required value rule._
+
+An optimal serialization is the valid serialization that uses the fewest components.
+
+The `serialize` method of the _version spec_ returns either the optimal serialization or the first invalid serialization.
+
+:::{figure-md} fig-serialize-1-2-3
+![How a version is serialized with values major=1, minor=2, and patch=3](../_static/serializing-a-version-1-2-3.svg)
+
+A version with values major=1, minor=2, and patch=3 only has one valid serialization. It is also the optimal serialization.
+:::
+
+:::{figure-md} fig-serialize-1-2-0
+![How a version is serialized with values major=1, minor=2, and patch=0](../_static/serializing-a-version-1-2-0.svg)
+
+A version with values major=1, minor=2, and patch=0 has two valid serializations. The optimal serialization is the one that uses the fewest components. `1.2` in this example
+:::
+
+:::{figure-md} fig-serialize-1-0-0
+![How a version is serialized with values major=1, minor=0, and patch=0](../_static/serializing-a-version-1-0-0.svg)
+
+A version with values major=1, minor=0, and patch=0 has three valid serializations. The optimal serialization is the one that uses the fewest components. `1` in this example.
+:::
+
+:::{figure-md} fig-serialize-1
+![How a version is serialized with invalid serialization formats](../_static/serializing-a-version-1.svg)
+
+A version with values major=1, minor=2, and patch=3 has no valid serializations in this example. The `serialize` method returns the first invalid serialization.
+:::

docsrc/reference/bumpversion/bumpversion.__main__.md

@@ -4,5 +4,6 @@
 ```
 
 ```{autodoc2-docstring} bumpversion.__main__
+:parser: myst
 :allowtitles:
 ```

docsrc/reference/bumpversion/bumpversion.aliases.md

@@ -4,6 +4,7 @@
 ```
 
 ```{autodoc2-docstring} bumpversion.aliases
+:parser: myst
 :allowtitles:
 ```
 
@@ -17,6 +18,7 @@
 
 * - {py:obj}`AliasedGroup <bumpversion.aliases.AliasedGroup>`
   - ```{autodoc2-docstring} bumpversion.aliases.AliasedGroup
+    :parser: myst
     :summary:
     ```
 ````
@@ -29,18 +31,21 @@
 Bases: {py:obj}`rich_click.rich_group.RichGroup`
 
 ```{autodoc2-docstring} bumpversion.aliases.AliasedGroup
+:parser: myst
 ```
 
 ```{rubric} Initialization
 ```
 
 ```{autodoc2-docstring} bumpversion.aliases.AliasedGroup.__init__
+:parser: myst
 ```
 
 ````{py:method} get_command(ctx: click.Context, cmd_name: str) -> typing.Optional[rich_click.Command]
 :canonical: bumpversion.aliases.AliasedGroup.get_command
 
 ```{autodoc2-docstring} bumpversion.aliases.AliasedGroup.get_command
+:parser: myst
 ```
 
 ````
@@ -49,6 +54,7 @@ Bases: {py:obj}`rich_click.rich_group.RichGroup`
 :canonical: bumpversion.aliases.AliasedGroup.resolve_command
 
 ```{autodoc2-docstring} bumpversion.aliases.AliasedGroup.resolve_command
+:parser: myst
 ```
 
 ````