feat: add docs (#5)

.github/ISSUE_TEMPLATE/BUG.yaml

@@ -0,0 +1,83 @@
+name: "Bug Report"
+description: Create an issue for a bug.
+title: "Bug: <title>"
+labels: ["bug", "triage required"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: "Description"
+      description: Please enter an description of the bug you are encountering
+      placeholder:
+    validations:
+      required: true
+  - type: input
+    id: reprod-url
+    attributes:
+      label: "URL to code causing the issue"
+      description: Please enter the URL to provide a reproduction of the issue, if applicable
+      placeholder: ex. https://github.com/USERNAME/REPO-NAME
+    validations:
+      required: false
+  - type: textarea
+    id: mcve
+    attributes:
+      label: "MCVE"
+      description: "Please provide a minimal, complete, and verifiable example of the issue."
+      value: |
+        ```py
+        # Your MCVE code here
+        ```
+      render: python
+    validations:
+      required: false
+  - type: textarea
+    id: reprod
+    attributes:
+      label: "Steps to reproduce"
+      description: Please enter the exact steps to reproduce the issue
+      value: |
+        1. Go to '...'
+        2. Click on '....'
+        3. Scroll down to '....'
+        4. See error
+      render: bash
+    validations:
+      required: false
+  - type: textarea
+    id: screenshot
+    attributes:
+      label: "Screenshots"
+      description: If applicable, add screenshots to help explain your problem.
+      value: |
+        "![SCREENSHOT_DESCRIPTION](SCREENSHOT_LINK.png)"
+      render: bash
+    validations:
+      required: false
+  - type: textarea
+    id: logs
+    attributes:
+      label: "Logs"
+      description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
+      render: bash
+    validations:
+      required: false
+  - type: textarea
+    id: version
+    attributes:
+      label: "Project Version"
+      description: What version of the project are you using when encountering this issue?
+    validations:
+      required: true
+  - type: checkboxes
+    id: platform
+    attributes:
+      label: "Platform"
+      description: What platform are you encountering the issue on?
+      options:
+        - label: "Linux"
+        - label: "Mac"
+        - label: "Windows"
+        - label: "Other (Please specify in the description above)"
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/DOCS.yaml

@@ -0,0 +1,13 @@
+name: "Documentation Update"
+description: Create an issue for documentation changes
+title: "Docs: <title>"
+labels: ["documentation"]
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: "Summary"
+      description: Provide a brief summary of your feature request
+      placeholder: Describe in a few lines your feature request
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/REQUEST.yaml

@@ -0,0 +1,37 @@
+name: "Feature Request"
+description: Create an issue for a new feature request
+title: "Enhancement: <title>"
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: "Summary"
+      description: Provide a brief summary of your feature request
+      placeholder: Describe in a few lines your feature request
+    validations:
+      required: true
+  - type: textarea
+    id: basic_example
+    attributes:
+      label: "Basic Example"
+      description: Indicate here some basic examples of your feature.
+      placeholder: Provide some basic example of your feature request
+    validations:
+      required: false
+  - type: textarea
+    id: drawbacks
+    attributes:
+      label: "Drawbacks and Impact"
+      description: What are the drawbacks or impacts of your feature request?
+      placeholder: Describe any the drawbacks or impacts of your feature request
+    validations:
+      required: false
+  - type: textarea
+    id: unresolved_question
+    attributes:
+      label: "Unresolved questions"
+      description: What, if any, unresolved questions do you have about your feature request?
+      placeholder: Identify any unresolved issues.
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yaml

@@ -0,0 +1 @@
+blank_issues_enabled: false

.github/dependabot.yaml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "daily"

.github/workflows/ci.yaml

@@ -0,0 +1,90 @@
+name: Tests and Linting
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+
+      - name: Install Pre-Commit
+        run: python -m pip install pre-commit && pre-commit install
+
+      - name: Load cached Pre-Commit Dependencies
+        id: cached-pre-commit-dependencies
+        uses: actions/cache@v3
+        with:
+          path: ~/.cache/pre-commit/
+          key: pre-commit-|${{ env.pythonLocation }}|${{ hashFiles('.pre-commit-config.yaml') }}
+
+      - name: Execute Pre-Commit
+        run: pre-commit run --show-diff-on-failure --color=always --all-files
+
+  test:
+    strategy:
+      fail-fast: true
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11"]
+    uses: ./.github/workflows/test.yaml
+    with:
+      python-version: ${{ matrix.python-version }}
+      coverage: ${{ matrix.python-version == '3.11' }}
+
+  test-platform-compat:
+    if: github.event_name == 'push'
+    strategy:
+      fail-fast: true
+      matrix:
+        os: ["macos-latest", "windows-latest"]
+    uses: ./.github/workflows/test.yaml
+    with:
+      python-version: "3.11"
+      os: ${{ matrix.os }}
+
+  sonar:
+    needs:
+      - test
+      - validate
+    if: github.event.pull_request.head.repo.fork == false && github.repository_owner == 'litestar-org'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+      - name: Download Artifacts
+        uses: actions/download-artifact@v3
+        with:
+          name: coverage-xml
+      - name: Fix coverage file for sonarcloud
+        run: sed -i "s/home\/runner\/work\/litestar\/litestar/github\/workspace/g" coverage.xml
+      - name: SonarCloud Scan
+        uses: sonarsource/sonarcloud-github-action@master
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+
+  codeql:
+    needs:
+      - test
+      - validate
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Initialize CodeQL Without Dependencies
+        uses: github/codeql-action/init@v2
+        with:
+          setup-python-dependencies: false
+          languages: python
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v2

.github/workflows/codeql.yml

@@ -0,0 +1,22 @@
+name: Scheduled CodeQL
+
+on:
+  schedule:
+    - cron: "0 4 * * *"
+
+jobs:
+  codeql:
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          ref: "main"
+
+      - name: Initialize CodeQL With Dependencies
+        uses: github/codeql-action/init@v2
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v2

.github/workflows/docs.yaml

@@ -0,0 +1,38 @@
+name: Documentation Building
+
+on:
+  release:
+    types: [published]
+
+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
+
+      - name: Fetch gh pages
+        run: git fetch origin gh-pages --depth=1
+
+      - name: Build docs
+        run: pdm run python tools/build_docs.py docs-build
+
+      - name: Deploy
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: docs-build

docs/_static/css/custom.css

@@ -0,0 +1,54 @@
+:root {
+  --brand-primary: #4b8bbe;
+  --brand-primary-rgb: 75, 139, 190;
+
+  --brand-secondary: #ffe873;
+  --brand-secondary-rgb: 255, 232, 115;
+
+  --brand-dark-blue: #306998;
+  --brand-dark-blue-rgb: 48, 105, 152;
+
+  --brand-yellow: #ffd43b;
+  --brand-yellow-rgb: 255, 212, 59;
+
+  --brand-dark: #646464;
+  --brand-dark-rgb: 100, 100, 100;
+
+  --brand-light: #ebdddd;
+  --brand-light-rgb: 235, 221, 221;
+}
+
+html.dark,
+html.light {
+  --sd-color-tabs-label-hover: var(--brand-secondary);
+}
+
+html.light {
+  --syntax-light-constant: var(--brand-primary);
+  --syntax-light-meta: var(--brand-primary);
+  /*  --syntax-light-text: #09090a;*/
+  /*  --syntax-light-cap-bg: #325b76;*/
+  /*  --syntax-light-pre-bg: #ddefff;*/
+  --syntax-light-keyword: var(--brand-primary);
+  --syntax-light-property: var(--brand-dark);
+}
+
+html.light .yue {
+  --yue-c-code-bg: var(--brand-yellow) !important;
+  --yue-c-code: var(--brand-dark) !important;
+  /*--yue-c-black: #11a1ff !important;*/
+}
+
+html.dark {
+  --syntax-dark-keyword: var(--brand-primary);
+  --syntax-dark-property: var(--brand-secondary);
+  --syntax-dark-constant: var(--brand-primary);
+  --syntax-dark-meta: var(--brand-primary);
+  --syntax-dark-pre-bg: rgba(var(--brand-primary-rgb), 0.1);
+}
+
+html.dark .yue {
+  --yue-c-code-bg: var(--brand-dark) !important;
+  --yue-c-code: var(--brand-secondary) !important;
+  /*--yue-c-black: #11a1ff !important;*/
+}

docs/api/index.rst

@@ -0,0 +1,11 @@
+=============
+API Reference
+=============
+
+.. toctree::
+    :titlesonly:
+    :caption: API Reference Documentation
+    :glob:
+    :hidden:
+
+    widgets/index

docs/api/widgets/index.rst

@@ -0,0 +1,6 @@
+=======
+widgets
+=======
+
+.. automodule:: src.widgets.events
+     :members: