📝 docs refactor

docs/cli.md

@@ -60,4 +60,4 @@ hatch-pip-compile --upgrade --all
 ```
 
 [pipx]: https://github.com/pypa/pipx
-[pip]: https://pip.pypa.io/en/stable/
+[pip]: https://pip.pypa.io

docs/cli_usage.md

@@ -0,0 +1,53 @@
+# Using the `hatch-pip-compile` CLI
+
+For convenience this package also makes a CLI available to handle the setting /
+unsetting of the `PIP_COMPILE_UPGRADE` / `PIP_COMPILE_UPGRADE_PACKAGE` environment variables
+and invoking the `hatch env run` command for you automatically. To use the CLI you'll need to
+install it outside your `pyproject.toml` / `hatch.toml` file.
+
+I recommend using [pipx] to
+install the CLI, but you can also install it directly with [pip]:
+
+```shell
+pipx install hatch-pip-compile
+```
+
+Once installed, you can run the CLI with the `hatch-pip-compile` command.
+
+## Examples
+
+### Upgrade the `default` environment
+
+The below command will upgrade all packages in the `default` environment.
+
+```shell
+hatch-pip-compile --upgrade
+```
+
+### Upgrade a non-default environment
+
+The below command will upgrade all packages in the `docs` environment.
+
+```shell
+hatch-pip-compile docs --upgrade
+```
+
+### Upgrade a specific package
+
+The below command will upgrade the `requests` package in the `default`
+environment.
+
+```shell
+hatch-pip-compile --upgrade-package requests
+```
+
+### Upgrade all `pip-compile` environments
+
+The below command will upgrade all packages in all `pip-compile` environments.
+
+```shell
+hatch-pip-compile --upgrade --all
+```
+
+[pipx]: https://github.com/pypa/pipx
+[pip]: https://pip.pypa.io

docs/contributing.md

@@ -181,10 +181,10 @@ would create a branch named `1.2.x` and merge your changes into that branch.
 See the [semantic-release documentation] for more information about
 branch based releases and other advanced release cases.
 
-[pipx]: https://pypa.github.io/pipx/
-[pre-commit]: https://pre-commit.com/
-[gitmoji]: https://gitmoji.dev/
-[conventional commits]: https://www.conventionalcommits.org/en/v1.0.0/
+[pipx]: https://pipx.pypa.io
+[pre-commit]: https://pre-commit.com
+[gitmoji]: https://gitmoji.dev
+[conventional commits]: https://www.conventionalcommits.org
 [semantic-release]: https://github.com/semantic-release/semantic-release
-[semantic-versioning]: https://semver.org/
+[semantic-versioning]: https://semver.org
 [semantic-release documentation]: https://semantic-release.gitbook.io/semantic-release/usage/configuration#branches

docs/examples.md

@@ -0,0 +1,239 @@
+# Examples
+
+## lock-filename
+
+The path (including the directory) to the ultimate lockfile. Defaults to `requirements.txt` in the project root
+for the `default` environment, and `requirements/requirements-{env_name}.txt` for non-default environments.
+
+Changing the lock file path:
+
+-   **_pyproject.toml_**
+
+    ```toml
+    [tool.hatch.envs.<envName>]
+    type = "pip-compile"
+    lock-filename = "locks/{env_name}.lock"
+    ```
+
+-   **_hatch.toml_**
+
+    ```toml
+    [envs.<envName>]
+    type = "pip-compile"
+    lock-filename = "locks/{env_name}.lock"
+    ```
+
+Changing the lock filename to a path in the project root:
+
+-   **_pyproject.toml_**
+
+    ```toml
+    [tool.hatch.envs.lint]
+    type = "pip-compile"
+    lock-filename = "linting-requirements.txt"
+    ```
+
+-   **_hatch.toml_**
+
+    ```toml
+    [envs.lint]
+    type = "pip-compile"
+    lock-filename = "linting-requirements.txt"
+    ```
+
+## pip-compile-constraint
+
+An environment to use as a constraint, ensuring that all shared dependencies are
+pinned to the same versions. For example, if you have a `default` environment and
+a `test` environment, you can set the `pip-compile-constraint` option to `default`
+on the `test` environment to ensure that all shared dependencies are pinned to the
+same versions. `pip-compile-constraint` can also be set to an empty string to disable
+the feature.
+
+-   **_pyproject.toml_**
+
+    ```toml
+    [tool.hatch.envs.default]
+    type = "pip-compile"
+
+    [tool.hatch.envs.test]
+    dependencies = [
+        "pytest"
+    ]
+    type = "pip-compile"
+    pip-compile-constraint = "default"
+    ```
+
+-   **_hatch.toml_**
+
+    ```toml
+    [envs.default]
+    type = "pip-compile"
+
+    [envs.test]
+    dependencies = [
+        "pytest"
+    ]
+    type = "pip-compile"
+    pip-compile-constraint = "default"
+    ```
+
+By default, all environments inherit from the `default` environment via
+[inheritance]. A common use case is to set the `pip-compile-constraint`
+and `type` options on the `default` environment and inherit them on
+all other environments. It's important to note that when `detached = true`,
+inheritance is disabled and the `type` and `pip-compile-constraint` options
+must be set explicitly.
+
+-   **_pyproject.toml_**
+
+    ```toml
+    [tool.hatch.envs.default]
+    type = "pip-compile"
+    pip-compile-constraint = "default"
+
+    [tool.hatch.envs.test]
+    dependencies = [
+        "pytest"
+    ]
+    ```
+
+-   **_hatch.toml_**
+
+    ```toml
+    [envs.default]
+    type = "pip-compile"
+    pip-compile-constraint = "default"
+
+    [envs.test]
+    dependencies = [
+        "pytest"
+    ]
+    ```
+
+## pip-compile-hashes
+
+Whether to generate hashes in the lockfile. Defaults to `false`.
+
+-   **_pyproject.toml_**
+
+    ```toml
+    [tool.hatch.envs.<envName>]
+    type = "pip-compile"
+    pip-compile-hashes = true
+    ```
+
+-   **_hatch.toml_**
+
+    ```toml
+    [envs.<envName>]
+    type = "pip-compile"
+    pip-compile-hashes = true
+    ```
+
+## pip-compile-args
+
+Extra arguments to pass to `pip-compile`. Custom PyPI indexes can be specified here.
+
+-   **_pyproject.toml_**
+
+    ```toml
+    [tool.hatch.envs.<envName>]
+    type = "pip-compile"
+    pip-compile-args = [
+        "--index-url",
+        "https://pypi.org/simple",
+    ]
+    ```
+
+-   **_hatch.toml_**
+
+    ```toml
+    [envs.<envName>]
+    type = "pip-compile"
+    pip-compile-args = [
+        "--index-url",
+        "https://pypi.org/simple",
+    ]
+    ```
+
+## pip-compile-verbose
+
+Set to `true` to run `pip-compile` in verbose mode instead of quiet mode.
+
+Optionally, if you would like to silence any warnings set the `pip-compile-verbose` option to `false`.
+
+-   **_pyproject.toml_**
+
+    ```toml
+    [tool.hatch.envs.<envName>]
+    type = "pip-compile"
+    pip-compile-verbose = true
+    ```
+
+-   **_hatch.toml_**
+
+    ```toml
+    [envs.<envName>]
+    type = "pip-compile"
+    pip-compile-verbose = true
+    ```
+
+## pip-compile-installer
+
+Whether to use [pip] or [pip-sync] to install dependencies into the project. Defaults to `pip`.
+When you choose the `pip` option the plugin will run `pip install -r {lockfile}` under the hood
+to install the dependencies. When you choose the `pip-sync` option `pip-sync {lockfile}` is invoked
+by the plugin.
+
+The key difference between these options is that `pip-sync` will uninstall any packages that are
+not in the lockfile and remove them from your environment. `pip-sync` is useful if you want to ensure
+that your environment is exactly the same as the lockfile. If the environment should be used
+across different Python versions and platforms `pip` is the safer option to use.
+
+-   **_pyproject.toml_**
+
+    ```toml
+    [tool.hatch.envs.<envName>]
+    type = "pip-compile"
+    pip-compile-installer = "pip-sync"
+    ```
+
+-   **_hatch.toml_**
+
+    ```toml
+    [envs.<envName>]
+    type = "pip-compile"
+    pip-compile-installer = "pip-sync"
+    ```
+
+## pip-compile-install-args
+
+Extra arguments to pass to `pip-compile-installer`. For example, if you'd like to use `pip` as the
+installer but want to pass the `--no-deps` flag to `pip install` you can do so with this option:
+
+-   **_pyproject.toml_**
+
+    ```toml
+    [tool.hatch.envs.<envName>]
+    type = "pip-compile"
+    pip-compile-installer = "pip"
+    pip-compile-install-args = [
+        "--no-deps"
+    ]
+    ```
+
+-   **_hatch.toml_**
+
+    ```toml
+    [envs.<envName>]
+    type = "pip-compile"
+    pip-compile-installer = "pip"
+    pip-compile-install-args = [
+        "--no-deps"
+    ]
+    ```
+
+[pip-sync]: https://github.com/jazzband/pip-tools
+[pip]: https://pip.pypa.io
+[inheritance]: hhttps://hatch.pypa.io/latest/config/environment/overview/#inheritance

docs/gen_pages.py

@@ -31,6 +31,7 @@
     mkdocs_gen_files.set_edit_path(full_doc_path, path)
 
 readme_content = Path("README.md").read_text(encoding="utf-8")
+readme_content = readme_content.replace("](docs/", "](")
 # Exclude parts that are between two exact `<!--skip-->` lines
 readme_content = "\n".join(readme_content.split("\n<!--skip-->\n")[::2])
 with mkdocs_gen_files.open("index.md", "w") as index_file:

docs/notes.md

@@ -0,0 +1,45 @@
+# Notes
+
+## Dev Dependencies
+
+Using the default hatch configuration, dev dependencies listed in your
+`default` environment (like `pytest`) will be included on the default lockfile
+(`requirements.txt`). If you want to remove your dev dependencies
+from the lockfile you must remove them from the `default` environment
+on your `pyproject.toml` / `hatch.toml` file.
+
+## Disabling Changes to the Lockfile
+
+In some scenarios, like in CI/CD, you may want to prevent the plugin from
+making changes to the lockfile. If you set the `PIP_COMPILE_DISABLE`
+environment variable to any non-empty value, the plugin will raise an error
+if it detects that the lockfile needs to be updated.
+
+```shell
+PIP_COMPILE_DISABLE=1 hatch env run python --version
+```
+
+## Manual Installation
+
+If you want to manually install this plugin instead of adding it to the
+`[tool.hatch.env]` table, you can do so with [pipx]:
+
+```bash
+pipx install hatch
+pipx inject hatch hatch-pip-compile
+```
+
+`pipx` also supports upgrading the plugin when any new versions are released:
+
+```shell
+pipx runpip hatch install --upgrade hatch-pip-compile
+```
+
+Alternatively, you can install the plugin directly with [pip]:
+
+```bash
+pip install hatch hatch-pip-compile
+```
+
+[pipx]: https://github.com/pypa/pipx
+[pip]: https://pip.pypa.io