Add docs (#284)

.github/docs-update.yml

@@ -0,0 +1,143 @@
+name: Publish Documentation
+
+on:
+  push:
+    branches:
+      - main
+      - docs-update
+    tags:
+      - '**'
+
+env:
+  COLUMNS: 150
+  PDM_DEPS: 'urllib3<2'
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+
+      - run: pip install -r src/python-fastui/requirements/all.txt
+      - run: pip install src/python-fastui
+
+      - run: npm install
+
+      - uses: pre-commit/action@v3.0.1
+        with:
+          extra_args: --all-files
+        env:
+          SKIP: no-commit-to-branch
+
+  test:
+    name: test ${{ matrix.python-version }} on ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-13, macos-latest]
+        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
+        exclude:
+          # Python 3.8 and 3.9 are not available on macOS 14
+          - os: macos-13
+            python-version: '3.10'
+          - os: macos-13
+            python-version: '3.11'
+          - os: macos-13
+            python-version: '3.12'
+          - os: macos-latest
+            python-version: '3.8'
+          - os: macos-latest
+            python-version: '3.9'
+
+    runs-on: ${{ matrix.os }}
+
+    env:
+      PYTHON: ${{ matrix.python-version }}
+      OS: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: set up python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - run: pip install -r src/python-fastui/requirements/test.txt
+      - run: pip install -r src/python-fastui/requirements/pyproject.txt
+      - run: pip install -e src/python-fastui
+
+      - run: coverage run -m pytest src
+      # display coverage and fail if it's below 80%, which shouldn't happen
+      - run: coverage report --fail-under=80
+
+      # test demo on 3.11 and 3.12, these tests are intentionally omitted from coverage
+      - if: matrix.python-version == '3.11' || matrix.python-version == '3.12'
+        run: pytest demo/tests.py
+
+      - run: coverage xml
+
+      - uses: codecov/codecov-action@v4
+        with:
+          file: ./coverage.xml
+          env_vars: PYTHON,OS
+
+  publish:
+    # Compare with the docs-build job in .github/workflows/ci.yml
+    needs: [lint, test]
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - name: checkout docs-site
+        uses: actions/checkout@v4
+        with:
+          ref: docs-site
+
+      - name: checkout current branch
+        uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+
+      - name: install
+        run: |
+          pip install --upgrade pip
+          pip install -r requirements/docs.txt
+          pip install --extra-index-url https://pydantic:${PPPR_TOKEN}@pppr.pydantic.dev/simple/ mkdocs-material mkdocstrings-python griffe-typedoc mkdocstrings-typescript
+          npm install
+          npm install -g typedoc
+        env:
+          PPPR_TOKEN: ${{ secrets.PPPR_TOKEN }}
+
+      - run: python -c 'import docs.plugins.main'
+
+      - name: Set git credentials
+        run: |
+          git config --global user.name "${{ github.actor }}"
+          git config --global user.email "${{ github.actor }}@users.noreply.github.com"
+
+      - run: mike deploy -b docs-site dev --push
+        if: "github.ref == 'refs/heads/main'"
+
+      - if: "github.ref == 'refs/heads/docs-update' || startsWith(github.ref, 'refs/tags/')"
+        id: check-version
+        uses: samuelcolvin/check-python-version@v4.1
+        with:
+          version_file_path: 'pydantic/version.py'
+          skip_env_check: true
+
+      - run: mike deploy -b docs-site ${{ steps.check-version.outputs.VERSION_MAJOR_MINOR }} latest --update-aliases --push
+        if: "(github.ref == 'refs/heads/docs-update' || startsWith(github.ref, 'refs/tags/')) && !fromJSON(steps.check-version.outputs.IS_PRERELEASE)"
+        env:
+          PYDANTIC_VERSION: v${{ steps.check-version.outputs.VERSION }}

.github/workflows/ci.yml

@@ -35,6 +35,29 @@ jobs:
         env:
           SKIP: no-commit-to-branch
 
+  docs-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+
+      - name: install
+        run: |
+          pip install --upgrade pip
+          pip install -r requirements/docs.txt
+          pip install --extra-index-url https://pydantic:${PPPR_TOKEN}@pppr.pydantic.dev/simple/ mkdocs-material mkdocstrings-python griffe-typedoc mkdocstrings-typescript
+          npm install
+          npm install -g typedoc
+        env:
+          PPPR_TOKEN: ${{ secrets.PPPR_TOKEN }}
+
+      - name: build site
+        run: mkdocs build --strict
+
   test:
     name: test ${{ matrix.python-version }} on ${{ matrix.os }}
     strategy:

.pre-commit-config.yaml

@@ -4,6 +4,7 @@ repos:
     hooks:
       - id: no-commit-to-branch
       - id: check-yaml
+        args: ['--unsafe']
       - id: check-toml
       - id: end-of-file-fixer
       - id: trailing-whitespace
@@ -27,6 +28,7 @@ repos:
         types_or: [javascript, jsx, ts, tsx, css, json, markdown]
         entry: npm run prettier
         language: system
+        exclude: '^docs/.*'
       - id: js-lint
         name: js-lint
         types_or: [ts, tsx]

Makefile

@@ -46,5 +46,13 @@ typescript-models:
 dev:
 	uvicorn demo:app --reload --reload-dir .
 
+.PHONY: docs
+docs:
+	mkdocs build
+
+.PHONY: serve
+serve:
+	mkdocs serve
+
 .PHONY: all
 all: testcov lint

build-docs.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+
+set -e
+set -x
+
+python3 -V
+
+python3 -m pip install -r ./requirements/docs.txt
+pip install --extra-index-url https://pydantic:$PPPR_TOKEN@pppr.pydantic.dev/simple/ mkdocs-material mkdocstrings-python griffe-typedoc mkdocstrings-typescript
+npm install
+npm install -g typedoc
+
+python3 -m mkdocs build

docs/api/python_components.md

@@ -0,0 +1,47 @@
+# Python Components
+
+::: fastui.components
+    handler: python
+    options:
+        inherited_members: true
+        docstring_options:
+            ignore_init_summary: false
+    members:
+        - Text
+        - Paragraph
+        - PageTitle
+        - Div
+        - Page
+        - Heading
+        - Markdown
+        - Code
+        - Json
+        - Button
+        - Link
+        - LinkList
+        - Navbar
+        - Modal
+        - ServerLoad
+        - Image
+        - Iframe
+        - FireEvent
+        - Error
+        - Spinner
+        - Toast
+        - Custom
+        - Table
+        - Pagination
+        - Display
+        - Details
+        - Form
+        - FormField
+        - ModelForm
+        - Footer
+        - AnyComponent
+        - FormFieldBoolean
+        - FormFieldFile
+        - FormFieldInput
+        - FormFieldSelect
+        - FormFieldSelectSearch
+
+<!-- TODO: don't render attributes in TOC -->

docs/api/typescript_components.md

@@ -0,0 +1,7 @@
+# TypeScript Components
+
+!!! warning "🚧 Work in Progress"
+    This page is a work in progress.
+
+::: @pydantic/fastui
+    handler: typescript

docs/extra/tweaks.css

@@ -0,0 +1,5 @@
+/* Revert hue value to that of pre mkdocs-material v9.4.0 */
+[data-md-color-scheme='slate'] {
+  --md-hue: 230;
+  --md-default-bg-color: hsla(230, 15%, 21%, 1);
+}

docs/guide.md

@@ -0,0 +1,2 @@
+!!! warning "🚧 Work in Progress"
+    This page is a work in progress.