Merge pull request #227 from callowayproject/doc-refactor

Updates to documentation
callowayproject · Aug 14, 2024 · a05ee53 · a05ee53
2 parents fad5797 + 0338da2
commit a05ee53
Show file tree

Hide file tree

Showing 41 changed files with 1,110 additions and 1,518 deletions.
diff --git a/Makefile b/Makefile
diff --git a/README.md b/README.md
@@ -92,7 +92,7 @@ The default configuration only allows bumping the major, minor, or patch version
 
 ### Add support for pre-release versions
 
-Alter the `parse` configuration to support pre-release versions. This `parse` option uses an extended (or verbose) regular expression to extract the version parts from the current version. 
+Alter the `parse` configuration to support pre-release versions. This `parse` option uses an extended (or verbose) regular expression to extract the version components from the current version. 
 
 ```toml title="New parse configuration"
 parse = """(?x)

diff --git a/bumpversion/bump.py b/bumpversion/bump.py
@@ -64,7 +64,7 @@ def do_bump(
     Bump the version_part to the next value or set the version to new_version.
 
     Args:
-        version_part: The version part to bump
+        version_part: The name of the version component to bump
         new_version: The explicit version to set
         config: The configuration to use
         config_file: The configuration file to update

diff --git a/bumpversion/cli.py b/bumpversion/cli.py
@@ -287,7 +287,7 @@ def bump(
     config = get_configuration(found_config_file, **overrides)
     if args:
         if args[0] not in config.parts.keys():
-            raise click.BadArgumentUsage(f"Unknown version part: {args[0]}")
+            raise click.BadArgumentUsage(f"Unknown version component: {args[0]}")
         version_part = args[0]
         files = args[1:]
     else:
@@ -335,7 +335,7 @@ def bump(
     required=False,
     envvar="BUMPVERSION_INCREMENT",
     type=str,
-    help="Increment the version part and add `new_version` to the configuration.",
+    help="Increment the version component and add `new_version` to the configuration.",
 )
 def show(args: List[str], config_file: Optional[str], format_: str, increment: Optional[str]) -> None:
     """

diff --git a/bumpversion/config/__init__.py b/bumpversion/config/__init__.py
@@ -70,7 +70,7 @@ def get_configuration(config_file: Union[str, Path, None] = None, **overrides: A
     parsed_config = read_config_file(config_file) if config_file else {}
     config_dict = set_config_defaults(parsed_config, **overrides)
 
-    # Set any missing version parts
+    # Set any missing version components
     config_dict["parts"] = get_all_part_configs(config_dict)
 
     # Set any missing file configuration

diff --git a/bumpversion/config/utils.py b/bumpversion/config/utils.py
@@ -13,7 +13,7 @@
 
 
 def get_all_file_configs(config_dict: dict) -> List[FileChange]:
-    """Make sure all version parts are included."""
+    """Make sure all version components are included."""
     defaults = {
         "parse": config_dict["parse"],
         "serialize": config_dict["serialize"],
@@ -31,7 +31,7 @@ def get_all_file_configs(config_dict: dict) -> List[FileChange]:
 
 
 def get_all_part_configs(config_dict: dict) -> Dict[str, VersionComponentSpec]:
-    """Make sure all version parts are included."""
+    """Make sure all version components are included."""
     try:
         parsing_groups = list(re.compile(config_dict["parse"]).groupindex.keys())
     except re.error as e:

diff --git a/bumpversion/files.py b/bumpversion/files.py
@@ -151,7 +151,7 @@ def _contains_change_pattern(
             return True
 
         # The `search` pattern did not match, but the original supplied
-        # version number (representing the same version part values) might
+        # version number (representing the same version component values) might
         # match instead. This is probably the case if environment variables are used.
 
         # check whether `search` isn't customized

diff --git a/docs/assets/explanations.jpg b/docs/assets/explanations.jpg
diff --git a/docs/assets/how-to.jpg b/docs/assets/how-to.jpg
diff --git a/docs/assets/reference.jpg b/docs/assets/reference.jpg
diff --git a/docs/assets/tutorial.jpg b/docs/assets/tutorial.jpg
diff --git a/docs/explanation/index.md b/docs/explanation/index.md
@@ -1 +1 @@
-# Explanation
+- *.md
diff --git a/docs/reference/subcommands/show.md → docs/explanation/show-subcommand.md b/docs/reference/subcommands/show.md → docs/explanation/show-subcommand.md
diff --git a/docs/reference/version-parts.md → docs/explanation/version-parts.md b/docs/reference/version-parts.md → docs/explanation/version-parts.md
@@ -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.

diff --git a/docs/gen_doc_stubs.py b/docs/gen_doc_stubs.py
@@ -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())
diff --git a/docs/howtos/avoid-incorrect-replacements.md b/docs/howtos/avoid-incorrect-replacements.md
@@ -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`:
 

diff --git a/docs/howtos/calver.md b/docs/howtos/calver.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
 

diff --git a/docs/howtos/index.md b/docs/howtos/index.md
diff --git a/docs/howtos/nav.md b/docs/howtos/nav.md
@@ -0,0 +1 @@
+- *.md
diff --git a/docs/index.md b/docs/index.md
@@ -5,10 +5,81 @@ title: Bump My Version
 
 # Bump My Version
 
-{% 
-    include-markdown 
-    "../README.md" 
-    start="<!--start-->" 
-    end="<!--end-->"
-    rewrite-relative-urls=false
-%}
+Bump My Version's purpose is to:
+
+- 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
+  - Support SemVer, CalVer, and other versioning schemes
+- 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
+
+## Installation
+
+You can download and install the latest version of this software from the Python package index (PyPI) as follows:
+
+```console
+pip install --upgrade bump-my-version
+```
+<!--
+## Jump to section
+
+::: 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/)
+            { .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.
+-->
diff --git a/docs/reference/calver_reference.md b/docs/reference/calver_reference.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.