docs: add docs (#23)

.github/workflows/docs-preview.yml

@@ -0,0 +1,72 @@
+name: Deploy Documentation Preview
+
+on:
+  workflow_run:
+    workflows: [Tests And Linting]
+    types: [completed]
+
+jobs:
+  deploy:
+    if: ${{ github.event.workflow_run.conclusion == 'success' &&  github.event.workflow_run.event == 'pull_request' }}
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Download artifact
+        uses: dawidd6/action-download-artifact@v2
+        with:
+          workflow_conclusion: success
+          run_id: ${{ github.event.workflow_run.id }}
+          path: docs-preview
+          name: docs-preview
+
+      - name: Set PR number
+        run: echo "PR_NUMBER=$(cat docs-preview/.pr_number)" >> $GITHUB_ENV
+
+      - name: Deploy docs preview
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: docs-preview/docs/_build/html
+          token: ${{ secrets.DOCS_PREVIEW_DEPLOY_TOKEN }}
+          repository-name: litestar-org/fast-query-parsers-docs-preview
+          clean: false
+          target-folder: ${{ env.PR_NUMBER }}
+          branch: gh-pages
+
+      - uses: actions/github-script@v6
+        env:
+          PR_NUMBER: ${{ env.PR_NUMBER }}
+        with:
+          script: |
+            const issue_number = process.env.PR_NUMBER
+            const body = "Documentation preview will be available shortly at https://litestar-org.github.io/fast-query-parsers-docs-preview/" + issue_number
+
+            const opts = github.rest.issues.listComments.endpoint.merge({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: issue_number,
+            });
+
+            const comments = await github.paginate(opts)
+
+            for (const comment of comments) {
+              if (comment.user.id === 41898282 && comment.body === body) {
+                await github.rest.issues.deleteComment({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  comment_id: comment.id
+                })
+              }
+            }
+
+            await github.rest.issues.createComment({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: issue_number,
+                  body: body,
+            })

.github/workflows/docs.yml

@@ -0,0 +1,46 @@
+name: Documentation Building
+
+on:
+  release:
+    types: [published]
+  push:
+    branches:
+      - main
+
+jobs:
+  docs:
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+
+      - uses: pdm-project/setup-pdm@v3
+        name: Set up PDM
+        with:
+          python-version: "3.11"
+          allow-python-prereleases: true
+          cache: true
+
+      - name: Install dependencies
+        run: pdm install -G:docs
+
+      - name: Fetch gh pages
+        run: git fetch origin gh-pages --depth=1
+
+      - name: Build release docs
+        run: pdm run python tools/build_docs.py docs-build
+        if: github.event_name == 'release'
+
+      - name: Build dev docs
+        run: pdm run python tools/build_docs.py docs-build
+        if: github.event_name == 'push'
+
+      - name: Deploy
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: docs-build

.gitignore

@@ -7,6 +7,7 @@ __pycache__/
 *.profraw
 coverage*
 .venv/
+/docs/_build/
 
 # pdm
 .pdm-python

CONTRIBUTING.rst

@@ -0,0 +1,23 @@
+============
+Contributing
+============
+
+All contributions are of course welcome!
+
+Repository Setup
+~~~~~~~~~~~~~~~~
+
+1. Run ``cargo build`` to set up the rust dependencies and ``pdm install`` to set up the python dependencies.
+2. Install the pre-commit hooks with ``pre-commit install`` (requires `pre-commit <https://pre-commit.com/>`_).
+
+Building
+~~~~~~~~
+
+Run ``pdm run maturin develop --release --strip`` to install a release wheel (without debugging info).
+This wheel can be used in tests and benchmarks.
+
+Benchmarking
+~~~~~~~~~~~~
+
+There are basic benchmarks using pyperf in place.
+To run these execute ``pdm run python benchmarks.py``.

Makefile

@@ -143,7 +143,7 @@ docs-clean: 										## Dump the existing built docs
 
 docs-serve: docs-clean 								## Serve the docs locally
 	@echo "=> Serving documentation"
-	$(ENV_PREFIX)sphinx-autobuild docs docs/_build/ -j auto --watch fast_query_parser.pyi --watch docs --watch tests --watch CONTRIBUTING.rst --port 8002
+	$(ENV_PREFIX)sphinx-autobuild docs docs/_build/ -j auto --watch fast_query_parser.pyi --watch docs --watch tests --watch CONTRIBUTING.rst --watch README.rst --port 8002
 
 docs: docs-clean 									## Dump the existing built docs and rebuild them
 	@echo "=> Building documentation"