Move plugin directory into documentation !stable-docs

.github/workflows/stable-docs.yml

@@ -0,0 +1,66 @@
+name: Update Stable Docs
+
+on:
+  release:
+    types: [published]
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  update_stable_docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - name: Set up Git user
+        run: |
+          git config user.name "Automated"
+          git config user.email "actions@users.noreply.github.com"
+      - name: Create stable branch if it does not yet exist
+        if: github.event_name != 'release' || !github.event.release.prerelease
+        run: |
+          if ! git ls-remote --exit-code --heads origin stable; then
+            git checkout -b stable
+            LATEST_RELEASE=$(git tag | sort -Vr | head -n1)
+            if [ -n "$LATEST_RELEASE" ]; then
+              rm -rf docs/
+              git checkout "$LATEST_RELEASE" -- docs/
+            fi
+            git add docs/
+            git commit -m "Populate docs/ from $LATEST_RELEASE" || echo "No changes"
+            git push -u origin stable
+          fi
+      - name: Handle release
+        if: github.event_name == 'release' && !github.event.release.prerelease
+        run: |
+          git fetch --all
+          git checkout -B stable origin/stable
+          git reset --hard "${GITHUB_REF#refs/tags/}"
+          git push origin stable --force
+      - name: Handle commit to main
+        if: contains(github.event.head_commit.message, '!stable-docs')
+        run: |
+          git fetch origin stable
+          git checkout -B stable origin/stable
+          CHANGED_DOCS="${RUNNER_TEMP}/changed-docs"
+          git diff-tree --no-commit-id --name-only -r -z "${{ github.sha }}" -- docs/ > "$CHANGED_DOCS"
+          if [[ -s "$CHANGED_DOCS" ]]; then
+            while IFS= read -r -d '' FILE; do
+              if git cat-file -e "${{ github.sha }}:$FILE" 2>/dev/null; then
+                git checkout "${{ github.sha }}" -- "$FILE"
+              else
+                git rm --ignore-unmatch -- "$FILE"
+              fi
+            done < "$CHANGED_DOCS"
+            git add docs/
+            git commit -m "Doc changes from ${{ github.sha }}"
+            git push origin stable
+          else
+            echo "No changes to docs/ in this commit."
+          fi

docs/index.rst

@@ -38,6 +38,7 @@ Contents
    python-api
    migrations
    plugins
+   plugin-directory
    reference
    cli-reference
    upgrading

docs/plugin-directory.rst

@@ -0,0 +1,57 @@
+.. _plugin_directory:
+
+==================
+ Plugin directory
+==================
+
+The following plugins are available for ``sqlite-utils``. Install them using
+the :ref:`sqlite-utils install <plugins>` command.
+
+SQL functions
+=============
+
+* `sqlite-utils-dateutil <https://github.com/simonw/sqlite-utils-dateutil>`__
+  adds date utility SQL functions, such as
+  ``select dateutil_parse('3rd november')``.
+* `sqlite-utils-jq <https://github.com/simonw/sqlite-utils-jq>`__ adds a
+  ``jq(document, expression)`` SQL function for running
+  `jq <https://jqlang.github.io/jq/>`__ programs against JSON documents
+  directly in SQLite.
+* `sqlite-utils-ml <https://github.com/rclement/sqlite-utils-ml>`__ by Romain
+  Clement adds functions for training machine learning models and running
+  predictions directly in SQLite.
+* Alex Garcia maintains plugins for his
+  `family of SQLite extensions <https://github.com/asg017/sqlite-ecosystem>`__:
+
+  * ``sqlite-utils-sqlite-regex``
+  * ``sqlite-utils-sqlite-path``
+  * ``sqlite-utils-sqlite-url``
+  * ``sqlite-utils-sqlite-ulid``
+  * ``sqlite-utils-sqlite-lines``
+  * ``sqlite-utils-sqlite-jsonschema``
+  * ``sqlite-utils-sqlite-tg``, which provides geospatial functions powered by
+    `TG <https://github.com/tidwall/tg>`__
+
+Interactive shells
+==================
+
+* `sqlite-utils-litecli <https://github.com/simonw/sqlite-utils-litecli>`__
+  adds an interactive SQLite shell with syntax highlighting and
+  auto-completion, started using ``sqlite-utils litecli data.db``.
+* `sqlite-utils-shell <https://github.com/simonw/sqlite-utils-shell>`__ adds a
+  basic interactive SQLite shell. Start an in-memory shell using
+  ``sqlite-utils shell``, or open a database using
+  ``sqlite-utils shell data.db``.
+
+Database utilities
+==================
+
+* `sqlite-utils-fast-fks <https://github.com/simonw/sqlite-utils-fast-fks>`__
+  brings back the fast ``db.add_foreign_keys()`` method that directly
+  manipulates the ``sqlite_master`` table. It also adds a
+  ``sqlite-utils fast-fks`` command.
+* `sqlite-utils-move-tables <https://github.com/simonw/sqlite-utils-move-tables>`__
+  adds ``sqlite-utils move-tables`` for moving tables between databases.
+
+Migration support is built into ``sqlite-utils`` itself. See
+:ref:`migrations` for the Python API and CLI usage.

docs/plugins.rst

@@ -6,6 +6,9 @@
 
 ``sqlite-utils`` supports plugins, which can be used to add extra features to the software.
 
+The :ref:`plugin directory <plugin_directory>` lists plugins that are
+available to install.
+
 Plugins can add new commands, for example ``sqlite-utils some-command ...``
 
 Plugins can be installed using the ``sqlite-utils install`` command: