feat: usage documentation (#293)

* feat: usage documentation

This is the initial implementation.  Expect many tweaks and adjustments in subsequent PRs.

.github/labeler.yml

@@ -0,0 +1,179 @@
+version: v1
+
+labels:
+  # -- types -------------------------------------------------------------------
+  - label: 'type/feat'
+    sync: true
+    matcher:
+      title: '^feat(\([^)]+\))?!?:'
+
+  - label: 'type/bug'
+    sync: true
+    matcher:
+      title: '^fix(\([^)]+\))?!?:'
+
+  - label: 'type/docs'
+    sync: true
+    matcher:
+      title: '^docs(\([^)]+\))?:'
+
+  - label: 'Breaking 🔨'
+    sync: true
+    matcher:
+      title: '^(feat|fix)(\([^)]+\))?!:'
+
+  # -- distinct areas ----------------------------------------------------------
+
+  - label: 'area/docs'
+    sync: true
+    matcher:
+      files:
+        any: ['docs/*', 'docs/**/*', '**/*.rst', '**/*.md']
+
+  - label: 'area/unit-tests'
+    sync: true
+    matcher:
+      files:
+        any: ['test/unit/*', 'test/unit/**/*', 'tests/*.py', 'tests/fixtures/**/*']
+
+  - label: 'area/integration-tests'
+    sync: true
+    matcher:
+      files:
+        any: ['test/integration/*', 'test/integration/**/*']
+
+  - label: 'area/example-apps'
+    sync: true
+    matcher:
+      files:
+        any: ['examples/**/*', 'examples/**/*']
+
+  - label: 'area/docs'
+    sync: true
+    matcher:
+      files:
+        any: ['docs/*', 'docs/**/*', '**/*.rst', '**/*.md']
+
+  - label: 'area/ci'
+    sync: true
+    matcher:
+      files:
+        any: ['.github/**/*', 'codecov.yml', 'pre-commit-config.yaml', 'sonar-project.properties', '*.yaml', '*.yml']
+
+  - label: 'area/dependencies'
+    sync: true
+    matcher:
+      files:
+        any: ['pyproject.toml', '*.lock']
+
+  - label: 'area/repositories'
+    sync: true
+    matcher:
+      files: ['advanced_alchemy/repository/**/*']
+
+  - label: 'area/services'
+    sync: true
+    matcher:
+      files: ['advanced_alchemy/service/**/*']
+
+  - label: 'area/base'
+    sync: true
+    matcher:
+      files: ['advanced_alchemy/base.py']
+
+  - label: 'area/exceptions'
+    sync: true
+    matcher:
+      files: ['advanced_alchemy/exceptions.py']
+
+  - label: 'area/filters'
+    sync: true
+    matcher:
+      files: ['advanced_alchemy/filters.py']
+
+  - label: 'area/operations'
+    sync: true
+    matcher:
+      files: ['advanced_alchemy/operations.py']
+
+  - label: 'area/mixins'
+    sync: true
+    matcher:
+      files: ['advanced_alchemy/mixins/**/*']
+
+  - label: 'area/config'
+    sync: true
+    matcher:
+      files: ['advanced_alchemy/config/**/*']
+
+  - label: 'area/alembic'
+    sync: true
+    matcher:
+      files: ['advanced_alchemy/alembic/**/*']
+
+  - label: 'area/flask'
+    sync: true
+    matcher:
+      files: ['advanced_alchemy/extensions/flask/**/*','advanced_alchemy/extensions/flask.py']
+
+- label: 'area/sanic'
+    sync: true
+    matcher:
+      files: ['advanced_alchemy/extensions/sanic/**/*','advanced_alchemy/extensions/sanic.py']
+
+- label: 'area/fastapi'
+    sync: true
+    matcher:
+      files: ['advanced_alchemy/extensions/starlette/**/*','advanced_alchemy/extensions/starlette.py']
+
+  - label: 'area/litestar'
+    sync: true
+    matcher:
+      files: ['advanced_alchemy/extensions/litestar/**/*']
+
+  - label: 'area/litestar'
+    sync: true
+    matcher:
+      files: ['advanced_alchemy/extensions/litestar/**/*']
+
+  - label: 'area/private-api'
+    sync: true
+    matcher:
+      files:
+        any: ['advanced_alchemy/_*.py', 'advanced_alchemy/*/_*.py', 'advanced_alchemy/_*/**/*.py']
+
+  - label: 'area/tools'
+    sync: true
+    matcher:
+      files: ['tools/**/*']
+
+  # -- Size Based Labels -------------------------------------------------------
+  - label: 'size: small'
+    sync: true
+    matcher:
+      files:
+        count:
+          gte: 1
+          lte: 10
+
+  - label: 'size: medium'
+    sync: true
+    matcher:
+      files:
+        count:
+          gte: 10
+          lte: 25
+
+  - label: 'size: large'
+    sync: true
+    matcher:
+      files:
+        count:
+          gte: 26
+
+# -- Merge Checks --------------------------------------------------------------
+checks:
+  - context: 'No Merge check'
+    description: "Disable merging when 'do not merge' label is set"
+    labels:
+      none: ['do not merge']

.github/workflows/ci.yml

@@ -161,6 +161,7 @@ jobs:
           files: coverage.xml
           token: ${{ secrets.CODECOV_TOKEN }}
           slug: litestar-org/advanced-alchemy
+
   build-docs:
     needs:
       - validate
@@ -185,10 +186,14 @@ jobs:
       - name: Build docs
         run: uv run make docs
 
-      - name: Save PR number
+      - name: Check docs links
         env:
-          PR_NUMBER: ${{ github.event.number }}
-        run: echo $PR_NUMBER > .pr_number
+          LITESTAR_DOCS_IGNORE_MISSING_EXAMPLE_OUTPUT: 1
+        run: uv run make docs-linkcheck
+
+      - name: Save PR number
+        run: |
+          echo "${{ github.event.number }}" > .pr_number
 
       - name: Upload artifact
         uses: actions/upload-artifact@v4
@@ -197,3 +202,4 @@ jobs:
           path: |
             docs/_build/html
             .pr_number
+          include-hidden-files: true

.github/workflows/notify-released-issues.yml

@@ -0,0 +1,32 @@
+name: Notify released issues
+on:
+  workflow_call:
+    inputs:
+      release_tag:
+        type: string
+        required: true
+
+jobs:
+  notify:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Get released issues
+        id: get-released-issues
+        run:
+          echo "issues=$(python ./.github/workflows/notify_released_issues/get_closed_issues.py ${{ inputs.release_tag }})" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/github-script@v7
+        env:
+          CLOSED_ISSUES: ${{ steps.get-released-issues.outputs.issues }}
+        with:
+          script: |
+            const script = require('./.github/workflows/notify_released_issues/notify.js')
+            await script({github, context, core})

.github/workflows/pr-labeler.yml

@@ -0,0 +1,48 @@
+name: "Pull Request Labeler"
+
+on:
+  pull_request_target:
+
+jobs:
+  apply-labels:
+    permissions:
+      contents: read
+      pull-requests: write
+      checks: write
+      statuses: write
+    runs-on: ubuntu-latest
+    steps:
+    - uses: fuxingloh/multi-labeler@v4
+      with:
+        github-token: "${{ secrets.GITHUB_TOKEN }}"
+
+  distinguish-pr-origin:
+    needs: apply-labels
+    if: ${{ always() }}
+    permissions:
+      pull-requests: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v7
+        with:
+          github-token: ${{secrets.GITHUB_TOKEN}}
+          script: |
+            const maintainers = [
+              'JacobCoffee', 'provinzkraut', 'cofin','Alc-Alc',
+              'dependabot[bot]', 'all-contributors[bot]'
+            ]
+            if (maintainers.includes(context.payload.sender.login)) {
+              github.rest.issues.addLabels({
+                issue_number: context.issue.number,
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                labels: ['pr/internal']
+              })
+            } else {
+              github.rest.issues.addLabels({
+                issue_number: context.issue.number,
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                labels: ['pr/external', 'Triage Required :hospital:']
+              })
+            }

.github/workflows/pr-merged.yml

@@ -0,0 +1,52 @@
+name: "PR merged"
+
+on:
+  pull_request:
+    types:
+      - closed
+    branches:
+      - main
+
+jobs:
+  close_and_notify:
+    name: Close issues and notify
+    if: github.event.pull_request.merged == true
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            const prNumber = context.payload.number
+            const branch = context.baseRef
+            // TODO: use semantic commits to specify the exact version, when it will be released
+            const commentBody = `<!--closing-comment-->\nThis issue has been closed in #${prNumber}. The change will be included in upcoming releases.`
+
+            const query = `query($number: Int!, $owner: String!, $name: String!) { repository(owner: $owner, name: $name) {
+                pullRequest(number: $number) {
+                      id
+                      closingIssuesReferences (first: 10) { edges { node { number } } }
+                      }
+                  }
+              }`
+            const res = await github.graphql(query, {number: prNumber, owner: context.repo.owner, name: context.repo.repo})
+            const linkedIssues = res.repository.pullRequest.closingIssuesReferences.edges.map(
+              edge => edge.node.number
+            )
+
+            for (const issueNumber of linkedIssues) {
+              const res = await github.rest.issues.update({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: issueNumber,
+                  state: "closed",
+                  state_reason: "completed"
+              })
+              if (res.status === 200) {
+                await github.rest.issues.createComment({
+                      owner: context.repo.owner,
+                      repo: context.repo.repo,
+                      issue_number: issueNumber,
+                      body: commentBody,
+                })
+              }
+            }

.github/workflows/publish.yml

@@ -29,3 +29,10 @@ jobs:
 
       - name: Publish package distributions to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
+
+  notify-issues:
+    needs: publish-release
+    name: Notify issues
+    uses: ./.github/workflows/notify-released-issues.yml
+    with:
+      release_tag: ${{ github.event.release.tag_name }}

.pre-commit-config.yaml

@@ -22,7 +22,7 @@ repos:
       - id: unasyncd
         additional_dependencies: ["ruff"]
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: "v0.7.4"
+    rev: "v0.8.0"
     hooks:
       # Run the linter.
     - id: ruff

CONTRIBUTING.rst

@@ -57,7 +57,7 @@ Running the docs locally
 
 To run or build the docs locally, you need to first install the required dependencies:
 
-``pdm install -G:docs``
+``make install``
 
 Then you can serve the documentation with ``make docs-serve``, or build them with ``make docs``.
 

Makefile

@@ -89,14 +89,7 @@ pre-commit: 										## Runs pre-commit hooks; includes ruff formatting and lin
 .PHONY: slotscheck
 slotscheck: 										## Run slotscheck
 	@echo "=> Running slotscheck"
-	@uv run slotscheck \
-		-m advanced_alchemy.config \
-		-m advanced_alchemy.repository \
-		-m advanced_alchemy.service \
-		-m advanced_alchemy.extensions \
-		-m advanced_alchemy.base \
-		-m advanced_alchemy.types \
-		-m advanced_alchemy.operations
+	@uv run slotscheck
 	@echo "=> slotscheck complete"
 
 .PHONY: fix