refactor: consolidate docs workflows and cleanup

- Merge docs-dev.yaml and docs-test.yaml into single docs.yaml
- Update migration tasks to remove more obsolete files
- Improve type annotations in __builtins__.pyi
- Remove unused pre-release workflow from release.yaml

Author: liblaf

.cspell.json

@@ -18,6 +18,7 @@
     "ipython",
     "libc",
     "liblaf",
+    "mathjax",
     "mkdocs",
     "mkdocstrings",
     "mypy",

.vscode/settings.json

@@ -1,5 +1,6 @@
 {
   "yaml.customTags": [
+    // ref: <https://squidfunk.github.io/mkdocs-material/creating-your-site/#minimal-configuration>
     "!ENV scalar",
     "!ENV sequence",
     "!relative scalar",

copier.yaml

@@ -7,7 +7,7 @@ _answers_file: .config/copier/.copier-answers.python.yaml
 _external_data:
   shared: "{{ answers_file_shared }}"
 
-_migrations:
+_migrations: &migrations
   - rm --force --verbose ".config/copier/direnv/00-python.sh"
   - rm --force --verbose ".config/copier/mise/scripts/setup-python.sh"
   - rm --force --verbose ".config/copier/python.just"
@@ -16,18 +16,25 @@ _migrations:
   - rm --force --verbose ".github/copier/mkdocs.yaml"
   - rm --force --verbose ".github/linters/.ruff.toml"
   - rm --force --verbose ".github/linters/pyrightconfig.json"
+  - rm --force --verbose ".github/workflows/docs-dev.yaml"
   - rm --force --verbose ".github/workflows/docs-stable.yaml"
-  - rm --force --verbose ".github/workflows/docs.yaml"
+  - rm --force --verbose ".github/workflows/docs-test.yaml"
   - rm --force --verbose ".github/workflows/shared-docs.yaml"
   - rm --force --verbose ".github/workflows/shared-release.yaml"
+  - rm --force --verbose "docs/css/fonts.css"
+  - rm --force --verbose "docs/css/mkdocstrings/api-autonav.css"
+  - rm --force --verbose "docs/css/mkdocstrings/material.css"
+  - rm --force --verbose "docs/css/mkdocstrings/syntax-highlight-in-signatures.css"
+  - rm --force --verbose "docs/javascript/mathjax.js"
+  - rm --force --verbose "docs/scripts/gen-ref-pages.py"
+  - rm --force --verbose "docs/SUMMARY.md"
 
 _skip_if_exists:
   - .config/mise/config.toml
   - .gitignore
   - .ruff.toml
   - .vscode/settings.json
   - docs/README.md
-  - docs/SUMMARY.md
   - mkdocs.yaml
   - pyproject.toml
   - pyrightconfig.json
@@ -39,19 +46,7 @@ _skip_if_exists:
 
 _subdirectory: template
 
-_tasks:
-  - rm --force --verbose ".config/copier/direnv/00-python.sh"
-  - rm --force --verbose ".config/copier/mise/scripts/setup-python.sh"
-  - rm --force --verbose ".config/copier/python.just"
-  - rm --force --verbose ".config/mise/conf.d/00-python.toml"
-  - rm --force --verbose ".github/copier/.copier-answers.python.yaml"
-  - rm --force --verbose ".github/copier/mkdocs.yaml"
-  - rm --force --verbose ".github/linters/.ruff.toml"
-  - rm --force --verbose ".github/linters/pyrightconfig.json"
-  - rm --force --verbose ".github/workflows/docs-stable.yaml"
-  - rm --force --verbose ".github/workflows/docs.yaml"
-  - rm --force --verbose ".github/workflows/shared-docs.yaml"
-  - rm --force --verbose ".github/workflows/shared-release.yaml"
+_tasks: *migrations
 
 answers_file_shared:
   type: str

template/.github/workflows/docs-test.yaml

@@ -1,12 +1,12 @@
 # This file is @generated by <https://github.com/liblaf/copier-python>.
 # DO NOT EDIT!
 
-name: Docs (Dev)
-
+name: Docs
 on:
   push:
-    branches:
-      - main
+    branches-ignore:
+      - assets**
+      - gh-pages
   workflow_dispatch:
 
 jobs:
@@ -32,9 +32,14 @@ jobs:
       - if: hashFiles('docs/scripts/pre-build.sh') != ''
         name: Pre-Build
         run: docs/scripts/pre-build.sh
-      - name: Deploy
+      - if: ${{ github.ref != 'refs/heads/main' }}
+        name: Build
+        run: mkdocs build
+      - if: ${{ github.ref == 'refs/heads/main' }}
+        name: Deploy
         run: mkdocs gh-deploy --force --no-history
-      - name: Setup GitHub Pages
+      - if: ${{ github.ref == 'refs/heads/main' }}
+        name: Setup GitHub Pages
         uses: liblaf/actions/setup-pages@main
         with:
           token: ${{ secrets.GH_PAT || steps.auth.outputs.token }}

template/.github/workflows/docs-dev.yaml template/.github/workflows/docs.yamltemplate/.github/workflows/docs-dev.yaml renamed to template/.github/workflows/docs.yaml

@@ -4,10 +4,6 @@
 name: Release
 
 on:
-  push:
-    branches-ignore:
-      - assets**
-      - gh-pages
   release:
     types:
       - published
@@ -46,42 +42,6 @@ jobs:
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
 
-  pre-release:
-    name: Pre-Release
-    permissions:
-      contents: write
-    needs:
-      - build
-    if: github.ref == 'refs/heads/main'
-    runs-on: ubuntu-latest
-    concurrency:
-      group: ${{ github.workflow }}-${{ github.ref }}-pre-release
-      cancel-in-progress: true
-    steps:
-      - id: auth
-        name: Auth App
-        uses: liblaf/actions/auth-app@main
-        with:
-          app-id: ${{ secrets.GH_APP_ID }}
-          private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - name: Download Artifacts
-        uses: actions/download-artifact@v4
-        with:
-          name: ${{ needs.build.outputs.artifact-name }}
-          path: dist/
-      - name: Create Pre-Release
-        uses: liblaf/actions/release@main
-        with:
-          clobber: true
-          files: dist/*
-          prerelease: true
-          tag: dev
-          token: ${{ steps.auth.outputs.token }}
-
   release:
     name: Release
     permissions:

template/.github/workflows/release.yaml

@@ -19,6 +19,7 @@
   "python.testing.pytestEnabled": true,
   "python.testing.unittestEnabled": false,
   "yaml.customTags": [
+    // ref: <https://squidfunk.github.io/mkdocs-material/creating-your-site/#minimal-configuration>
     "!ENV scalar",
     "!ENV sequence",
     "!relative scalar",

template/.vscode/settings.json

@@ -1,3 +1,21 @@
+# This file is @generated by <https://github.com/liblaf/copier-python>.
+# DO NOT EDIT!
+
 # ref: <https://github.com/microsoft/pyright/blob/main/docs/builtins.md>
 
-from icecream import ic as ic
+from typing import overload, type_check_only
+
+@type_check_only
+class _IceCreamDebugger:
+    @overload
+    def __call__(self) -> None: ...
+    @overload
+    def __call__[T](self, arg: T) -> T: ...
+    @overload
+    def __call__[T1, T2, *Ts](
+        self, arg1: T1, arg2: T2, *args: *Ts
+    ) -> tuple[T1, T2, *Ts]: ...
+
+ic: _IceCreamDebugger
+
+__all__ = ["ic"]