Updated documentation

Author: coordt

docs/assets/explanations.jpg

@@ -1 +1 @@
-# Explanation
+- *.md

docs/assets/how-to.jpg

@@ -1,4 +1,4 @@
-# Version parts
+# Version components
 
 - The version string is the rendering of some or all version parts.
 - While the version string may be rendered differently in various places, the value for all parts is maintained in Bump My Version's configuration.

docs/assets/reference.jpg

@@ -47,5 +47,5 @@
 
     mkdocs_gen_files.set_edit_path(full_doc_path, path)
 
-with mkdocs_gen_files.open("reference/api/SUMMARY.md", "w") as nav_file:
+with mkdocs_gen_files.open("reference/api/nav.md", "w") as nav_file:
     nav_file.writelines(nav.build_literate_nav())

docs/assets/tutorial.jpg

@@ -1,4 +1,4 @@
-# Avoiding incorrect replacements
+# Avoid incorrect replacements
 
 In files that have multiple version strings, Bump My Version may find the wrong string and replace it. Given this `requirements.txt` for `MyProject`:
 

docs/explanation/index.md

@@ -7,7 +7,6 @@ For this example, we will use the following format: `YYYY.MM.DD.patch`. It will
 - `2022.2.1` for the first patch of February 1, 2022
 - `2022.2.1.1` for the second patch of February 1, 2022
 
-
 ## Initial configuration
 
 ```toml title=".bumpversion.toml"
@@ -31,7 +30,12 @@ You can look up the regular expressions for the CalVer format in the [CalVer ref
 
 ## Expected behavior
 
-You can find out more about the logic behind the CalVer incrementing in the [CalVer reference](../reference/calver_reference.md#calver-incrementing-logic).
+- CalVer version components are marked as `always_increment` by default.
+- When bumping a version, you specify which component to increment. It is called the target component.
+- When bumping a version, the components marked as `always_increment` are incremented first.
+- If an `always_increment` component's value changed, its dependent components are marked for reset to their default values.
+- If the target component is in the set of components marked for reset, the target component is reset to its default value.
+- If the target component is not in the set of components marked for reset, the target component is incremented and its dependent components are reset to their default values.
 
 ### Bumping the release resets the patch part
 

docs/reference/subcommands/show.md docs/explanation/show-subcommand.md

@@ -5,10 +5,56 @@ title: Bump My Version
 
 # Bump My Version
 
-{% 
-    include-markdown 
-    "../README.md" 
-    start="<!--start-->" 
-    end="<!--end-->"
-    rewrite-relative-urls=false
-%}
+::: grid wide-gap
+
+    ::: card-container
+
+        ::: card-media
+
+            ![Tutorials](assets/tutorial.jpg)
+
+        ::: card-content
+
+            [Tutorials](tutorials/getting-started.md)
+            { .card-content-title }
+
+            Follow along with our guides to learn how to use Bump My Version.
+
+    ::: card-container
+
+        ::: card-media
+
+            ![Reference](assets/reference.jpg)
+
+        ::: card-content
+
+            [Reference](reference/index.md)
+            { .card-content-title }
+
+            Consult the reference for specifics about the Bump My Version's configuration and commands.
+
+    ::: card-container
+
+        ::: card-media
+
+            ![How-To's](assets/how-to.jpg)
+
+        ::: card-content
+
+            [How-To's](howtos/index.md)
+            { .card-content-title }
+
+            Need to get something done? Check out our how-to guides.
+
+    ::: card-container
+
+        ::: card-media
+
+            ![Explanations](assets/explanations.jpg)
+
+        ::: card-content
+
+            [Explanations](explanation/index.md)
+            { .card-content-title }
+
+            Want to understand the library better? Read our explanations behind the design.

docs/reference/version-parts.md docs/explanation/version-parts.md

@@ -2,7 +2,9 @@
 
 ## Calendar versioning codes
 
-The following table lists the available format codes for calendar versioning (CalVer) schemes. The codes can be used to define the version format in the `calver_format` configuration options. Formatting codes, surrounded by `{ }` can be combined to create a custom version format. For example, the format `YYYY.MM.DD` can be defined as `"{YYYY}.{MM}.{DD}"`.
+The following table lists the available format codes for calendar versioning (CalVer) schemes. The codes can be used to
+define the version format in the `calver_format` configuration options. Formatting codes, surrounded by `{ }` can be
+combined to create a custom version format. For example, the format `YYYY.MM.DD` can be defined as `"{YYYY}.{MM}.{DD}"`.
 
 | Code   | Example(s)          | Comment                                       |
 |--------|---------------------|-----------------------------------------------|
@@ -32,7 +34,6 @@ The following table lists the available format codes for calendar versioning (Ca
 calver_format = "{YYYY}.{MM}.{DD}"
 ```
 
-
 ## Parsing CalVer versions
 
 Using the following chart, we can set up the version parsing:
@@ -68,7 +69,9 @@ Using the following chart, we can set up the version parsing:
 
     `(?:jan|fév|mar|avr|mai|jui|jui|aoû|sep|oct|nov|déc)` for French
 
-You can use these regular expressions to parse CalVer versions in your project. For example, the following `parse` configuration can be used to parse a version string in the format `YYYY.MM.DD` as the `release` part of the version string:
+You can use these regular expressions to parse CalVer versions in your project. For example, the following `parse`
+configuration can be used to parse a version string in the format `YYYY.MM.DD` as the `release` part of the version
+string:
 
 ```toml
 [tool.bumpversion]
@@ -80,12 +83,3 @@ parse = """(?x)                      # Verbose mode
     )
 """
 ```
-
-## CalVer incrementing logic
-
-- CalVer version components are marked as `always_increment` by default.
-- When bumping a version, you specify which component to increment. It is called the target component.
-- When bumping a version, the components marked as `always_increment` are incremented first.
-- If an `always_increment` component's value changed, its dependent components are marked for reset to their default values.
-- If the target component is in the set of components marked for reset, the target component is reset to its default value.
-- If the target component is not in the set of components marked for reset, the target component is incremented and its dependent components are reset to their default values.