Updated README and other documentation

README.md

@@ -1,53 +1,157 @@
 # Bump My Version
 
-Version bump your Python project
+[![image](https://img.shields.io/pypi/v/bump-my-version.svg)](https://pypi.org/project/bump-my-version/)
+[![image](https://img.shields.io/pypi/l/bump-my-version.svg)](https://pypi.org/project/bump-my-version/)
+[![image](https://img.shields.io/pypi/pyversions/bump-my-version.svg)](https://pypi.org/project/bump-my-version/)
+[![GitHub Actions](https://github.com/callowayproject/bump-my-version/workflows/CI/badge.svg)](https://github.com/callowayproject/bump-my-version/actions)
 
-*Put a meaningful, short, plain-language description of:* 
+> **NOTE**
+>
+> This is a maintained refactor of the [bump2version fork of](https://github.com/c4urself/bump2version) the excellent [bumpversion project](https://github.com/peritus/bumpversion). The main goals of this refactor were:
+>
+> - Add support for `pyproject.toml` configuration files.
+> - Convert to [click](https://click.palletsprojects.com/en/8.1.x/) for and [rich](https://rich.readthedocs.io/en/stable/index.html) for the CLI interface
+> - Add better configuration validation using [Pydantic](https://docs.pydantic.dev)
+> - Make the code and tests easier to read and maintain
 
-- *what this project is trying to accomplish.*
-- *why it matters.* 
-- *the problem(s) this project solves.*
-- *how this software can improve the lives of its audience.*
-- *what sets this apart from related-projects. Linking to another doc or page is OK if this can't be expressed in a sentence or two.*
 
-**Technology stack:** *Indicate the technological nature of the software, including primary programming language(s) and whether the software is intended as standalone or as a module in a framework or other ecosystem.*
+## Overview
 
-**Status:** *Alpha, Beta, 1.1, etc. It's OK to write a sentence, too. The goal is to let interested people know where this project is at. This is also a good place to link to the CHANGELOG.md.*
+Version-bump your software with a single command!
 
-**Links:** to production or demo instances
+A small command line tool to simplify releasing software by updating all
+version strings in your source code by the correct increment. Also creates
+commits and 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 and PyPy3
 
-## Dependencies
 
-*Describe any dependencies that must be installed for this software to work. This includes programming languages, databases or other storage mechanisms, build tools, frameworks, and so forth. If specific versions of other software are required, or known not to work, call that out.*
+## Alternatives
+
+If bump-my-version does not fully suit your needs, you could take a look
+at other tools doing similar or related tasks:
+[ALTERNATIVES.md](https://github.com/c4urself/bump-my-version/blob/master/RELATED.md).
 
 ## Installation
 
-_Detailed instructions on how to install, configure, and get the project running. This should be frequently tested to ensure reliability. Alternatively, link to a separate INSTALL document._
+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
+```
 
-## Configuration
+## Changelog
 
-_If the software is configurable, describe it in detail, either here or in other documentation to which you link._
+Please find the changelog here: [CHANGELOG.md](CHANGELOG.md)
 
 ## Usage
 
-_Show users how to use the software. Be specific. Use appropriate formatting when showing code snippets._
+> **NOTE:** 
+>
+> Throughout this document, you can use `bumpversion` or `bump-my-version` interchangeably.
+
+There are two modes of operation: On the command line for single-file operation and using a configuration file for more complex multi-file operations.
+
+    bump-my-version [options] part [file]
+
+### `part`
+
+_**required**_
+
+The part of the version to increase, e.g. `minor`.
+
+Valid values include the named groups defined in the `parse` configuration.
+
+Example bumping 0.5.1 to 0.6.0:
+
+    bump-my-version --current-version 0.5.1 minor
+
+### `file`
+
+_**[optional]**_<br />
+**default**: none
+
+Additional files to modify.
+
+These files are added to the list of files specified in your configuration file. If you want to rewrite only files specified on the command line, also use `--no-configured-files`.
+
+Example bumping 1.1.9 to 2.0.0:
+
+    bump-my-version --current-version 1.1.9 major setup.py
+
+## Configuration file
+
+`bump-my-version` looks in four places for the configuration file to parse (in order of precedence):
+
+1. `--config-file <FILE>` _(command line argument)_
+2. `BUMPVERSION_CONFIG_FILE=file` _(environment variable)_
+3. `.bumpversion.cfg` _(legacy)_
+4. `.bumpversion.toml`
+5. `setup.cfg` _(legacy)_
+6. `pyproject.toml`
+
+`.toml` files are recommended due to their type handling. We will likely drop support for `ini`-style formats in the future due to issues with formatting and parsing. You should add your configuration file to your source code management system.
+
+By using a configuration file, you no longer need to specify those options on the command line. The configuration file also allows greater flexibility in specifying how files are modified.
+
+## Command-line Options
+
+Most of the configuration values above can also be given as an option on the command line.
+Additionally, the following options are available:
+
+`--dry-run, -n`
+Don't touch any files, just pretend. Best used with `--verbose`.
+
+`--no-configured-files`
+Will not update/check files specified in the configuration file.
+
+Similar to dry-run, but will also avoid checking the files. Also useful when you want to update just one file with e.g., `bump-my-version --no-configured-files major my-file.txt`
+
+`--verbose, -v`
+Print useful information to stderr. If specified more than once, it will output more information.
+
+`--list`
+List machine-readable information to stdout for consumption by other programs.
+
+Example output:
+
+    current_version=0.0.18
+    new_version=0.0.19
+
+`-h, --help`
+Print help and exit
+
+## Using bumpversion in a script
+
+If you need to use the version generated by bumpversion in a script you can make use of the `--list` option, combined with `grep` and `sed`.
+
+Say for example that you are using git-flow to manage your project and want to automatically create a release. When you issue `git flow release start` you already need to know the new version, before applying the change.
+
+The standard way to get it in a bash script is
 
-## How to test the software
+    bump-my-version --dry-run --list <part> | grep <field name> | sed -r s,"^.*=",,
 
-_If the software includes automated tests, detail how to run those tests._
+where `part` is as usual the part of the version number you are updating. You need to specify `--dry-run` to avoid bumpversion acting.
 
-## Known issues
+For example, if you are updating the minor number and looking for the new version number this becomes
 
-_Document any known significant shortcomings with the software._
+    bump-my-version --dry-run --list minor | grep new_version | sed -r s,"^.*=",,
 
-## Getting help
+## Development & Contributing
 
-_Instruct users how to get help with this software; this might include links to an issue tracker, wiki, mailing list, etc._
+Thank you, contributors! You can find a full list here: https://github.com/callowayproject/bump-my-version/graphs/contributors
 
+See also our [CONTRIBUTING.md](CONTRIBUTING.md)
 
-## Getting involved
+Development of this happens on GitHub, patches including tests, and documentation
+are very welcome, as well as bug reports! Also please open an issue if this
+tool does not support every aspect of bumping versions in your development
+workflow, as it is intended to be very versatile.
 
-_This section should detail why people should get involved and describe key areas you are currently focusing on; e.g., trying to get feedback on features, fixing certain bugs, building important pieces, etc._
+## License
 
-_General instructions on how to contribute should be stated with a link to CONTRIBUTING.md._
+bump-my-version is licensed under the MIT License - see the [LICENSE](LICENSE) file for details

docsrc/_static/css/custom.css

@@ -1,11 +1,37 @@
 .class .sig-prename.descclassname {
   display: none;
 }
+
 .subheading {
   line-height: 1.25;
   margin-bottom: 0;
   color: #646776;
 }
+
 .subheading + section > h1 {
   margin-top: 0;
 }
+
+.field-list p {
+  margin: 0;
+}
+
+dl.field-list {
+  display: grid;
+  grid-template-columns: fit-content(30%) auto;
+  margin-bottom: 1rem;
+}
+
+dl.field-list > dt {
+  font-weight: bold;
+  word-break: break-word;
+  padding-left: 0.5em;
+  padding-right: 5px;
+}
+
+dl.field-list > dd {
+  padding-left: 0.5em;
+  margin-top: 0;
+  margin-left: 0;
+  margin-bottom: 0;
+}

docsrc/cli.rst

@@ -1,6 +1,6 @@
 Command-line Interface
 ======================
 
-.. click:: bump_version.cli:cli
-   :prog: bump_version
+.. click:: bumpversion.cli:cli
+   :prog: bumpversion
    :nested: full

docsrc/conf.py

@@ -11,8 +11,8 @@
 import bumpversion
 
 project = "bump-my-version"
-copyright = f"{date.today():%Y}, C H Robinson"
-author = "Data Science Team"
+copyright = f"{date.today():%Y} Calloway Project"
+author = "Contributors"
 
 version = bumpversion.__version__
 release = bumpversion.__version__
@@ -64,6 +64,7 @@
     "smartquotes",
     "substitution",
     "tasklist",
+    "fieldlist",
 ]
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),