diff --git a/.github/workflows/stable-docs.yml b/.github/workflows/stable-docs.yml new file mode 100644 index 000000000..81ded6d88 --- /dev/null +++ b/.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 diff --git a/docs/index.rst b/docs/index.rst index f190d4745..899a0ec77 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -38,6 +38,7 @@ Contents python-api migrations plugins + plugin-directory reference cli-reference upgrading diff --git a/docs/plugin-directory.rst b/docs/plugin-directory.rst new file mode 100644 index 000000000..5d1e57783 --- /dev/null +++ b/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 ` command. + +SQL functions +============= + +* `sqlite-utils-dateutil `__ + adds date utility SQL functions, such as + ``select dateutil_parse('3rd november')``. +* `sqlite-utils-jq `__ adds a + ``jq(document, expression)`` SQL function for running + `jq `__ programs against JSON documents + directly in SQLite. +* `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 `__: + + * ``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 `__ + +Interactive shells +================== + +* `sqlite-utils-litecli `__ + adds an interactive SQLite shell with syntax highlighting and + auto-completion, started using ``sqlite-utils litecli data.db``. +* `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 `__ + 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 `__ + 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. diff --git a/docs/plugins.rst b/docs/plugins.rst index 99588eec2..8e103e7f4 100644 --- a/docs/plugins.rst +++ b/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 ` 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: