From f7d9dadf68e11f22bef289323784e23daaac19b2 Mon Sep 17 00:00:00 2001 From: Oleh Prypin Date: Sat, 9 Dec 2023 16:32:47 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20refactor=20docs=20generation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 📝 switch to a Markdown extension that displays better on GitHub * 📝 deduplicate source of README.md/index.md * 📝 simplify and unnest nav generation #40 --- README.md | 4 + docs/contributing.md | 24 +- docs/{gen_ref_pages.py => gen_pages.py} | 15 +- docs/index.md | 417 ------------------------ mkdocs.yaml | 6 +- requirements/requirements-docs.txt | 4 + 6 files changed, 32 insertions(+), 438 deletions(-) rename docs/{gen_ref_pages.py => gen_pages.py} (70%) delete mode 100644 docs/index.md 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-pip-compile -

- -

-hatch plugin to use pip-compile to manage project dependencies and lockfiles. -

- -

- PyPI - PyPI - Python Version - GitHub License - Hatch project - Ruff - pre-commit - semantic-release - Gitmoji -

- -## 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