diff --git a/README.md b/README.md
index c24dc51..87cb15d 100644
--- a/README.md
+++ b/README.md
@@ -407,6 +407,8 @@ Alternatively, you can install it with [pip]:
pip install hatch hatch-pip-compile
```
+
+
---
---
@@ -417,6 +419,8 @@ pip install hatch hatch-pip-compile
#### See the [Changelog]
+
+
[pip-compile]: https://github.com/jazzband/pip-tools
[pip-sync]: https://github.com/jazzband/pip-tools
[hatch]: https://github.com/pypa/hatch
diff --git a/docs/contributing.md b/docs/contributing.md
index c87817e..2b55e41 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -2,13 +2,13 @@
## Environment Setup
-!!! tip "pipx"
-
- This documentaion uses [pipx] to
- install and manage non-project command line tools like `hatch` and
- `pre-commit`. If you don't already have `pipx` installed, make sure to
- see their [documentation](https://pypa.github.io/pipx/installation/).
- If you prefer not to use `pipx`, you can use `pip` instead.
+> TIP: **pipx**
+>
+> This documentaion uses [pipx] to
+> install and manage non-project command line tools like `hatch` and
+> `pre-commit`. If you don't already have `pipx` installed, make sure to
+> see their [documentation](https://pypa.github.io/pipx/installation/).
+> If you prefer not to use `pipx`, you can use `pip` instead.
1. Install [hatch](https://github.com/pypa/hatch)
@@ -16,11 +16,11 @@
pipx install hatch
```
- !!! note "pre-commit"
-
- Hatch will attempt to set up pre-commit hooks for you using
- [pre-commit]. If you don't already,
- make sure to install pre-commit as well: `pipx install pre-commit`
+ > NOTE: **pre-commit**
+ >
+ > Hatch will attempt to set up pre-commit hooks for you using
+ > [pre-commit]. If you don't already,
+ > make sure to install pre-commit as well: `pipx install pre-commit`
2. Build the Virtual Environment
diff --git a/docs/gen_ref_pages.py b/docs/gen_pages.py
similarity index 70%
rename from docs/gen_ref_pages.py
rename to docs/gen_pages.py
index 412500e..8c4dde0 100644
--- a/docs/gen_ref_pages.py
+++ b/docs/gen_pages.py
@@ -11,7 +11,6 @@
project_dir = Path(__file__).resolve().parent.parent
source_code = project_dir.joinpath("hatch_pip_compile")
-nav = mkdocs_gen_files.Nav()
for path in sorted(source_code.rglob("*.py")):
module_path = path.relative_to(project_dir).with_suffix("")
@@ -26,13 +25,15 @@
elif parts[-1] == "__main__":
continue
- nav[parts] = doc_path.as_posix()
-
with mkdocs_gen_files.open(full_doc_path, "w") as fd:
- ident = ".".join(parts)
- fd.write(f"::: {ident}")
+ fd.write(f"# `{parts[-1]}`\n\n::: {'.'.join(parts)}")
mkdocs_gen_files.set_edit_path(full_doc_path, path)
-with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
- nav_file.writelines(nav.build_literate_nav())
+
+with open("README.md") as in_file:
+ readme_content = in_file.read()
+# Exclude parts that are between two exact `` lines
+readme_content = "\n".join(readme_content.split("\n\n")[::2])
+with mkdocs_gen_files.open("index.md", "w") as index_file:
+ index_file.write(readme_content)
diff --git a/docs/index.md b/docs/index.md
deleted file mode 100644
index f4aad4d..0000000
--- a/docs/index.md
+++ /dev/null
@@ -1,417 +0,0 @@
-hatch-pip-compile
-
-
- 
-
-
-
-hatch plugin to use pip-compile to manage project dependencies and lockfiles.
-
-
-
- 
- 
- 
- 
- 
- 
- 
- 
-
-
-## Installation
-
-Declare `hatch-pip-compile` as a dependency in your `pyproject.toml` file under the
-`[tool.hatch.env]` table and hatch will automatically install it. You must also have
-your environment type set to `pip-compile` (see [Configuration](#configuration)).
-
-- **_pyproject.toml_**
-
- ```toml
- [tool.hatch.env]
- requires = [
- "hatch-pip-compile"
- ]
-
- [tool.hatch.envs.default]
- type = "pip-compile"
- ```
-
-- **_hatch.toml_**
-
- ```toml
- [env]
- requires = [
- "hatch-pip-compile"
- ]
-
- [envs.default]
- type = "pip-compile"
- ```
-
-## Usage
-
-The `hatch-pip-compile` plugin will automatically run `pip-compile` whenever your
-environment needs to be updated. Behind the scenes, this plugin creates a lockfile
-at `requirements.txt` (non-default lockfiles are located at
-`requirements/requirements-{env_name}.txt`). Once the dependencies are resolved
-the plugin will install the lockfile into your virtual environment.
-
-- [lock-filename](#lock-filename) - changing the default lockfile path
-- [pip-compile-constraint](#pip-compile-constraint) - syncing dependency versions across environments
-- [Upgrading Dependencies](#upgrading-dependencies) - how to upgrade dependencies
-
-## Configuration
-
-The [environment plugin] name is `pip-compile`. Set your environment
-type to `pip-compile` to use this plugin for the respective environment.
-
-- **_pyproject.toml_**
-
- ```toml
- [tool.hatch.envs.default]
- type = "pip-compile"
- ```
-
-- **_hatch.toml_**
-
- ```toml
- [envs.default]
- type = "pip-compile"
- ```
-
-### Configuration Options
-
-The plugin gives you options to configure how lockfiles are generated and how they are installed
-into your environment.
-
-#### Generating Lockfiles
-
-| name | type | description |
-| ---------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| lock-filename | `str` | The filename of the ultimate lockfile. `default` env is `requirements.txt`, non-default is `requirements/requirements-{env_name}.txt` |
-| pip-compile-constraint | `str` | An environment to use as a constraint file, ensuring that all shared dependencies are pinned to the same versions. |
-| pip-compile-hashes | `bool` | Whether to generate hashes in the lockfile. Defaults to `false`. |
-| pip-compile-verbose | `bool` | Set to `true` to run `pip-compile` in verbose mode instead of quiet mode, set to `false` to silence warnings |
-| pip-compile-args | `list[str]` | Additional command-line arguments to pass to `pip-compile` |
-
-#### Installing Lockfiles
-
-| name | type | description |
-| ------------------------ | ----------- | ---------------------------------------------------------------------------------------------- |
-| pip-compile-installer | `str` | Whether to use `pip` or `pip-sync` to install dependencies into the project. Defaults to `pip` |
-| pip-compile-install-args | `list[str]` | Additional command-line arguments to pass to `pip-compile-installer` |
-
-#### 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.]
- type = "pip-compile"
- lock-filename = "locks/{env_name}.lock"
- ```
-
-- **_hatch.toml_**
-
- ```toml
- [envs.]
- 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.
-
-- **_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.]
- type = "pip-compile"
- pip-compile-hashes = true
- ```
-
-- **_hatch.toml_**
-
- ```toml
- [envs.]
- 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.]
- type = "pip-compile"
- pip-compile-args = [
- "--index-url",
- "https://pypi.org/simple",
- ]
- ```
-
-- **_hatch.toml_**
-
- ```toml
- [envs.]
- 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.]
- type = "pip-compile"
- pip-compile-verbose = true
- ```
-
-- **_hatch.toml_**
-
- ```toml
- [envs.]
- 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.]
- type = "pip-compile"
- pip-compile-installer = "pip-sync"
- ```
-
-- **_hatch.toml_**
-
- ```toml
- [envs.]
- 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.]
- type = "pip-compile"
- pip-compile-installer = "pip"
- pip-compile-install-args = [
- "--no-deps"
- ]
- ```
-
-- **_hatch.toml_**
-
- ```toml
- [envs.]
- type = "pip-compile"
- pip-compile-installer = "pip"
- pip-compile-install-args = [
- "--no-deps"
- ]
- ```
-
-## Upgrading Dependencies
-
-Upgrading all dependencies can be as simple as deleting your lockfile and
-recreating it by reactivating the environment:
-
-```shell
-rm requirements.txt
-hatch env run --env default -- python --version
-```
-
-If you're a user of the `--upgrade` / `--upgrade-package` options on `pip-compile`,
-these features can be enabled on this plugin using the environment variables
-`PIP_COMPILE_UPGRADE` and `PIP_COMPILE_UPGRADE_PACKAGE`. When either of these
-environment variables are set `hatch` will force the lockfile to be regenerated
-whenever the environment is activated.
-
-To run with `upgrade` functionality on the `default` environment:
-
-```shell
-PIP_COMPILE_UPGRADE=1 hatch env run --env default -- python --version
-```
-
-To run with `upgrade-package` functionality on the `docs` environment:
-
-```shell
-PIP_COMPILE_UPGRADE_PACKAGE="mkdocs,mkdocs-material" hatch env run --env docs -- python --version
-```
-
-The above commands call `python --version` on a particular environment,
-but the same behavior applies to any script that activates the environment.
-
-## 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
-```
-
-Alternatively, you can install it with [pip]:
-
-```bash
-pip install hatch hatch-pip-compile
-```
-
-[pip-compile]: https://github.com/jazzband/pip-tools
-[pip-sync]: https://github.com/jazzband/pip-tools
-[hatch]: https://github.com/pypa/hatch
-[pipx]: https://github.com/pypa/pipx
-[Docs]: https://juftin.github.io/hatch-pip-compile/
-[Contributing Guide]: https://juftin.github.io/hatch-pip-compile/contributing
-[Changelog]: https://github.com/juftin/hatch-pip-compile/releases
-[environment plugin]: https://hatch.pypa.io/latest/plugins/environment/
-[pip]: https://pip.pypa.io/en/stable/
-[inheritance]: https://hatch.pypa.io/1.7/config/environment/overview/#inheritance
diff --git a/mkdocs.yaml b/mkdocs.yaml
index d6a0441..2a36eb0 100644
--- a/mkdocs.yaml
+++ b/mkdocs.yaml
@@ -34,6 +34,8 @@ remote_branch: gh-pages
copyright: Copyright © 2023 Justin Flannery
extra:
generator: false
+exclude_docs: |
+ gen_pages.py
markdown_extensions:
- toc:
permalink: "#"
@@ -51,7 +53,7 @@ markdown_extensions:
- pymdownx.keys
- pymdownx.tasklist
- pymdownx.tilde
- - admonition
+ - callouts
- pymdownx.details
- pymdownx.emoji
- pymdownx.tabbed:
@@ -61,7 +63,7 @@ plugins:
- markdown-exec
- gen-files:
scripts:
- - docs/gen_ref_pages.py
+ - docs/gen_pages.py
- literate-nav:
nav_file: SUMMARY.md
- section-index
diff --git a/requirements/requirements-docs.txt b/requirements/requirements-docs.txt
index 91a07be..4c013e0 100644
--- a/requirements/requirements-docs.txt
+++ b/requirements/requirements-docs.txt
@@ -3,6 +3,7 @@
#
# [constraints] requirements.txt (SHA256: 9dc610f2c50b92a04dc522873ebc8dd69d35bf8ce9feeef14c5341e8e4ef3019)
#
+# - markdown-callouts
# - markdown-exec
# - mkdocs
# - mkdocs-gen-files
@@ -119,11 +120,14 @@ keyring==24.3.0
# hatch
markdown==3.5.1
# via
+ # markdown-callouts
# mkdocs
# mkdocs-autorefs
# mkdocs-material
# mkdocstrings
# pymdown-extensions
+markdown-callouts==0.3.0
+ # via hatch.envs.docs
markdown-exec==1.7.0
# via hatch.envs.docs
markdown-it-py==3.0.0