Execute linting in CI caching project-config cache directory

.github/workflows/ci.yml

@@ -21,8 +21,17 @@ jobs:
           python-version: "3.10"
       - name: Install dependencies
         run: pip install -U hatch
+      - name: Get project-config cache directory
+        id: project-config-cache
+        run: echo "directory=$(hatch --quiet --no-interactive run project-config show cache)" >> $GITHUB_OUTPUT
+      - name: Cache project-config
+        uses: actions/cache@v3
+        with:
+          path: ${{ steps.project-config-cache.outputs.directory }}
+          key: ${{ steps.project-config-cache.outputs.directory }}
       - name: Lint
         run: hatch run style:lint
+
   test:
     name: Test
     runs-on: ${{ matrix.platform }}

docs/index.rst

@@ -22,6 +22,7 @@ multiple projects.
    reference/config
    reference/styling
    reference/plugins
+   reference/ci
 
 .. toctree::
    :maxdepth: 3

docs/reference/ci.rst

@@ -0,0 +1,52 @@
+***********
+Using on CI
+***********
+
+You can speed up the execution on CI systems caching the directory
+used by **project-config** to store the persistent cache between runs.
+
+This directory is output to STDOUT executing ``project-config show cache``
+
+.. note::
+
+   The cache will be stored the time defined at ``cache``
+   configuration field.
+
+Github Actions
+==============
+
+.. code-block:: yaml
+
+   name: CI
+
+   on:
+     workflow_dispatch:
+     pull_request:
+     push:
+       branches:
+         - master
+       tags:
+         - v*
+
+   jobs:
+     lint:
+       name: Lint
+       runs-on: ubuntu-latest
+       steps:
+         - uses: actions/checkout@v3
+         - name: Set up Python
+           uses: actions/setup-python@v4
+           with:
+             python-version: "3.10"
+         - name: Install dependencies
+           run: pip install project-config
+         - name: Get project-config cache directory
+           id: project-config-cache
+           run: echo "directory=$(project-config show cache)" >> $GITHUB_OUTPUT
+         - name: Cache project-config
+           uses: actions/cache@v3
+           with:
+             path: ${{ steps.project-config-cache.outputs.directory }}
+             key: ${{ steps.project-config-cache.outputs.directory }}
+         - name: Lint
+           run: hatch run style:lint

docs/reference/config.rst

@@ -94,6 +94,13 @@ Also accept the next string to not use the cache at all.
    ``--nocache`` or setting the ``PROJECT_CONFIG_USE_CACHE`` environment
    variable to ``"false"``.
 
+.. seealso::
+
+   You can use the command ``project-config show cache`` to output
+   the location of project-config's cache directory.
+
+   :doc:`./cli`
+
 ``cli`` (`object`)
 ==================
 

pyproject.toml

@@ -128,7 +128,7 @@ python -c 'import webbrowser as w;w.open("http://127.0.0.1:8089")' &&
 python -m http.server 8089 -b localhost -d docs/_build/html"""
 
 [tool.project-config]
-cache = "2 days"
+cache = "30 days"
 style = [
   # Basic Python style: use Hatch, pre-commit, Github workflows, etc
   "gh://mondeja/project-config-styles@v4.2/python/base.json5",

tests/test_docs/test_ci_data.py

@@ -0,0 +1,31 @@
+import os
+
+from testing_helpers import rootdir
+
+
+CI_REFERENCE_FILEPATH = os.path.join(
+    rootdir,
+    "docs",
+    "reference",
+    "ci.rst",
+)
+
+PYPROJECT_TOML_FILEPATH = os.path.join(rootdir, "pyproject.toml")
+
+
+def test_ci_reference_github_actions_python_version():
+    expected_python_version = None
+    with open(PYPROJECT_TOML_FILEPATH, encoding="utf-8") as f:
+        lines = f.read().splitlines()
+        for i, line in enumerate(lines):
+            if line == "[tool.hatch.envs.default]":
+                expected_python_version = lines[i + 1].split('"')[1]
+                break
+
+    with open(CI_REFERENCE_FILEPATH, encoding="utf-8") as f:
+        assert f'python-version: "{expected_python_version}"' in f.read(), (
+            "The python version in the CI reference file does not"
+            " match the python version in pyproject.toml"
+            f" ({expected_python_version})."
+            " Please update the CI reference file."
+        )