Merge pull request #69 from jacebrowning/4.x-docs

Update docs for 4.x release

CHANGELOG.md

@@ -1,6 +1,6 @@
 # Revision History
 
-# 4.0 (alpha)
+## 4.0 (beta)
 
 - **BREAKING:** Removed `<owner/repo>` CLI argument in favor of automatic detection.
 - Updated the default CLI command to display metrics and launch the report.

README.md

@@ -17,13 +17,12 @@ The official command-line client for [The Coverage Space](http://coverage.space)
 
 ## Installation
 
-Install this library directly into an activated virtual environment:
+Install this tool globally with [pipx](https://pipxproject.github.io/pipx/) (or pip):
 
 ```text
-$ pip install coveragespace
+$ pipx install coveragespace
 ```
-
-or add it to your [Poetry](https://poetry.eustace.io/) project:
+or add it to your [Poetry](https://python-poetry.org/docs/) project:
 
 ```text
 $ poetry add coveragespace
@@ -33,18 +32,24 @@ $ poetry add coveragespace
 
 To update the value for a test coverage metric:
 
-```sh
-$ coveragespace <owner/repo> <metric>
+```text
+$ coveragespace set <metric>
 ```
 
-For example, after testing with code coverage enabled:
+where `<metric>` is one of:
+
+- **unit**
+- **integration**
+- **overall**
 
-```sh
-$ coveragespace owner/repo unit
+For example, after running unit tests with code coverage enabled:
+
+```text
+$ coveragespace set unit
 ```
 
-will attempt to extract the current coverage data from your working tree and compare that with the last known value. The coverage value can also be manually specified:
+which will attempt to extract the current coverage data from your project directory and compare that with the last known value. The coverage value can also be manually specified:
 
-```sh
-$ coveragespace <owner/repo> <metric> <value>
+```text
+$ coveragespace set <metric> <value>
 ```

docs/advanced.md

@@ -1,23 +1,41 @@
-# Metrics Reset
+# Advanced Usage
+
+The client can also be used to view and reset coverage metrics.
+
+## Viewing Reports
+
+To update the overall coverage metric and view the local coverage report:
+
+```text
+$ coveragespace
+```
+
+or to simply view the current report:
+
+```text
+$ coveragespace view
+```
+
+## Resetting Metrics
 
 If code coverage metrics have decreased, but you would like to silence the warning and reset metrics to the next received value:
 
-```sh
-$ coveragespace <owner/repo> --reset
+```text
+$ coveragespace reset
 ```
 
-# Verbosity
+## Increasing Verbosity
 
 To always display the coverage results, use the `--verbose` option:
 
-```sh
-$ coveragespace <owner/repo> <metric> --verbose
+```text
+$ coveragespace set <metric> --verbose
 ```
 
-# Exit Codes
+## Exit Codes
 
 To return a non-zero exit code when coverage decreases, use the `--exit-code` option:
 
-```sh
-$ coveragespace <owner/repo> <metric> --exit-code
+```text
+$ coveragespace set <metric> --exit-code
 ```

docs/formats.md

@@ -1,9 +1,19 @@
 # Supported Formats
 
-The client currently supports the following coverage formats:
+The client extracts project metadata and coverage information from the project directory.
+
+## Source Code Repositories
+
+It currently supports the following repository formats:
+
+- [Git](https://git-scm.com/)
+
+## Coverage Data Formats
+
+It currently supports the following coverage formats:
 
 - [coverage.py](https://coverage.readthedocs.org/)
 
-# Additional Formats
+## Additional Formats
 
-Support for additional coverage formats is greatly appreciated. Please follow the [contributor instructions](https://github.com/jacebrowning/coverage-space-cli/blob/main/CONTRIBUTING.md) to add support for a new format.
+Support for additional formats is greatly appreciated! Please follow the [contributor instructions](https://github.com/jacebrowning/coverage-space-cli/blob/main/CONTRIBUTING.md) to add support for a new repository or coverage format.

mkdocs.yml

@@ -10,7 +10,7 @@ theme: readthedocs
 nav:
   - Home: index.md
   - Advanced Usage: advanced.md
-  - Coverage Formats: formats.md
+  - Supported Formats: formats.md
   - About:
       - Release Notes: about/changelog.md
       - Contributing: about/contributing.md

pyproject.toml

@@ -1,7 +1,7 @@
 [tool.poetry]
 
 name = "coveragespace"
-version = "4.0a4"
+version = "4.0b1"
 description = "A place to track your code coverage metrics."
 
 license = "MIT"