From c078c85a16078c3b09710e3148c464afa12a8676 Mon Sep 17 00:00:00 2001 From: Greg Burd Date: Fri, 31 Jul 2026 14:02:37 -0400 Subject: [PATCH] docs: complete landing index + add manual gh-pages publish job Rewrite docs-src/index.md to link the full modernized tree (C + C++/STL API, all guides, man pages, per-book PDFs) now that phases 1-5 are done. Add a workflow_dispatch publish job to docs.yml that regenerates HTML+PDF+man and pushes them to gh-pages under /reference/, leaving the landing page and the historical archive untouched. --- .github/workflows/docs.yml | 42 ++++++++++++++++++++++++++ docs-src/index.md | 62 ++++++++++++++++++++++++++++++++------ 2 files changed, 95 insertions(+), 9 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 38dafbbb0..666df0224 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -192,3 +192,45 @@ jobs: lychee --no-progress --scheme http --scheme https \ --exclude "localhost" --max-concurrency 8 \ "docs-build/html/**/*.html" || true' + + # ---------------------------------------------------------------------------- + # Publish (manual): regenerate HTML + PDF + man and push them to the gh-pages + # branch under /reference/ (Pages is legacy branch-based, served from + # gh-pages:/). workflow_dispatch only -- publishing is a deliberate act, not + # something every push should do. The landing page (gh-pages:/index.html) and + # the historical archive (gh-pages:/docs/) are left untouched. + # ---------------------------------------------------------------------------- + publish: + name: publish to gh-pages (manual) + runs-on: ubuntu-latest + if: github.event_name == 'workflow_dispatch' + permissions: + contents: write + steps: + - uses: actions/checkout@v4 + - name: Install Nix (flakes enabled) + uses: cachix/install-nix-action@v27 + with: + extra_nix_config: | + experimental-features = nix-command flakes + - name: Build the full site (HTML + PDF + man) + run: nix develop --command bash -c 'cd docs-src && python3 build.py' + - name: Deploy /reference/ to gh-pages + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + ver=$(sed -n 's/^DB_VERSION_PATCH=//p' dist/RELEASE) + full="5.3.$ver" + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + tar czf "/tmp/libdb-man-$full.tar.gz" -C docs-build/man man3 + git fetch origin gh-pages + git worktree add /tmp/ghp origin/gh-pages + rm -rf /tmp/ghp/reference + mkdir -p /tmp/ghp/reference/pdf + cp -r docs-build/html/* /tmp/ghp/reference/ + cp docs-build/pdf/*.pdf /tmp/ghp/reference/pdf/ + cp "/tmp/libdb-man-$full.tar.gz" "/tmp/ghp/reference/libdb-man-$full.tar.gz" + ( cd /tmp/ghp && git add -A && \ + git commit -m "Publish documentation reference ($full) [ci]" && \ + git push origin HEAD:gh-pages ) diff --git a/docs-src/index.md b/docs-src/index.md index 4789a86c9..3fde681a8 100644 --- a/docs-src/index.md +++ b/docs-src/index.md @@ -3,16 +3,60 @@ title: "Berkeley DB Documentation" --- # Berkeley DB Documentation -Reference documentation for Berkeley DB, generated from Markdown source. +The complete reference for **libdb** (Berkeley DB) — the embedded, +transactional key/value storage engine. Generated from Markdown source by +`docs-src/build.py`; available as HTML (here), [PDF](#pdf), and +[man pages](#man). Version and copyright are single-sourced from +`docs-src/_data/site.toml` + `dist/RELEASE`. -This tree is the modernized replacement for the lost-source DocBook HTML: one -Markdown file per topic, rendered to HTML (and, in later phases, PDF and man -pages) by `docs-src/build.py`. Version and copyright live in one place -(`docs-src/_data/site.toml` + `dist/RELEASE`), not duplicated per page. +## API reference -## Reference +- [C API Reference](api/c/index.html) — the primary interface: `DB_ENV`, `DB`, + `DBC` (cursor), `DBT`, transactions, locking, logging, replication, and the + command-line utilities. +- [C++ / STL API Reference](api/stl/index.html) — the `dbstl` standard-template- + library containers and iterators backed by Berkeley DB. -- [C API Reference](api/c/index.html) +## Guides -*(C++/STL API, the Getting Started guides, the Programmer's Reference, and the -other trees are migrated in follow-up phases.)* +- [Programmer's Reference](guides/programmer_reference/index.html) — the + conceptual manual: access methods, the environment, memory pool, locking, + logging, transactions, replication, XA, and tuning. +- [Getting Started with Data Storage](guides/gsg/index.html) — databases, + cursors, secondary indexes, the four access methods. +- [Getting Started with Transactions](guides/gsg_txn/index.html) — ACID, + isolation, deadlocks, recovery, checkpoints. +- [Getting Started with Replication](guides/gsg_db_rep/index.html) — the + replication framework and Replication Manager. +- [Collections (Bindings) Tutorial](guides/collections/index.html) — the + Java-style collections/bindings API. +- [Berkeley DB SQL](guides/bdb-sql/index.html) — the SQLite-compatible SQL + interface. +- [Installation & Build](guides/installation/index.html) — building on Unix, + Windows, Android; configuration flags; the test suite. +- [Upgrading](guides/upgrading/index.html) — release-to-release upgrade notes + (2.0 through 4.7 and the 11gR2 line). +- [Porting](guides/porting/index.html) — porting Berkeley DB to a new platform. +- Articles: [In-Memory Databases](guides/articles/inmemory/index.html) · + [Message Text](guides/articles/mssgtxt/index.html). + +## Man pages + +Every public API has a section-3 man page, plus a library overview +(**`libdb(3)`**). They are built to `docs-build/man/man3/` (787 pages) and +shipped in the release man-page tarball. Install and use like any system man +page, e.g. `man libdb`, `man db_get`. + +## PDF downloads + +Each book is also available as a PDF (see the release assets / `docs-build/pdf/`): +`api_c.pdf`, `api_stl.pdf`, `guides_programmer_reference.pdf`, +`guides_gsg.pdf`, `guides_gsg_txn.pdf`, `guides_gsg_db_rep.pdf`, +`guides_collections.pdf`, `guides_bdb-sql.pdf`, `guides_installation.pdf`, +`guides_upgrading.pdf`, `guides_porting.pdf`, +`guides_articles_inmemory.pdf`, `guides_articles_mssgtxt.pdf`. + +--- + +*The C#/Java language-binding manuals (Sandcastle / Javadoc, not DocBook) are +archived separately and are not part of this Markdown-sourced tree.*