chore: generate docs in markdown

Add the command `just pgai generate-docs` to update the docs.

The `just install-commit-hook` will also install a hook that updates the
docs automatically, if any `projects/pgai/pgai/*.python` file changes.

Author: alejandrodnm

.github/workflows/ci.yml

@@ -156,6 +156,15 @@ jobs:
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
 
+      - name: Check if docs are outdated
+        run: |
+          just pgai generate-docs
+          if git diff --name-only HEAD -- projects/pgai/docs/.generated-files.txt | grep -q . ; then
+            echo "::error:: Documentation is out of date. Please run 'just pgai generate-docs', or install the git hooks 'just install-git-hooks' and commit"
+            exit 1
+          fi
+          echo "Documentation is up to date!"
+
   build-and-test-pgai-db-module:
     needs: authorize
     runs-on: ubuntu-latest
@@ -222,4 +231,4 @@ jobs:
           source venv/bin/activate
           pip install --upgrade pip
           pip install -e .
-        working-directory: ./projects/pgai
+        working-directory: ./projects/pgai

.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+default_install_hook_types:
+  - pre-commit
+  - commit-msg
+
+repos:
+  - repo: local
+    hooks:
+      - id: update-docs
+        name: Update pydoc-markdown documentation
+        entry: bash -c 'uv tool run pydoc-markdown && git add docs/api.md'
+        language: system
+        files: ^projects/pgai/pgai/.*\.py$
+        pass_filenames: false
+        stages: [pre-commit]
+
+  - repo: https://github.com/compilerla/conventional-pre-commit
+    rev: v4.2.0
+    hooks:
+      - id: conventional-pre-commit
+        stages: [commit-msg]
+        args: [--verbose]

justfile

@@ -19,6 +19,5 @@ ci:
 
 # Install semantic commit message hook
 @install-commit-hook:
-  curl --fail -s -o .git/hooks/commit-msg https://raw.githubusercontent.com/hazcod/semantic-commit-hook/master/commit-msg
-  chmod u+x .git/hooks/commit-msg
-  echo "commit-msg hook installed"
+  uv tool install pre-commit
+  uv tool run pre-commit install

projects/pgai/Dockerfile

@@ -3,7 +3,7 @@ ENV PYTHONDONTWRITEBYTECODE=1 \
     PYTHONUNBUFFERED=1 \
     UV_PROJECT_ENVIRONMENT=/usr/local/
 WORKDIR /build
-COPY --from=ghcr.io/astral-sh/uv:0.5.20 /uv /uvx /bin/
+COPY --from=ghcr.io/astral-sh/uv:0.7.10 /uv /uvx /bin/
 
 COPY pyproject.toml uv.lock ./
 
@@ -25,4 +25,4 @@ COPY pgai /app/pgai
 USER pgaiuser
 
 ENTRYPOINT ["python", "-m", "pgai", "vectorizer", "worker"]
-CMD ["-c", "4"]
+CMD ["-c", "4"]

projects/pgai/docs/.generated-files.txt

@@ -0,0 +1,2 @@
+md5 70ef3c2ad36ca5b33c7d95e13bbf3076 api/semantic-catalog.md
+md5 0c00cb79ede0d48d765b7ce43a2d0d74 mkdocs.yml