diff --git a/.github/workflows/check-docs.yml b/.github/workflows/check-docs.yml index d1e0fc5ba..f06cd7e07 100644 --- a/.github/workflows/check-docs.yml +++ b/.github/workflows/check-docs.yml @@ -1,4 +1,5 @@ -name: Compile js-doc and build mdBook +name: Check docs +# Builds all documentation sources: js-doc, mdBook, and Sphinx. on: push: @@ -8,24 +9,50 @@ on: branches: - '**' jobs: - build-and-deploy: + check-docs: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v4 + with: + persist-credentials: false + fetch-depth: 0 + + # --- js-doc --- + - name: Set up Node.js - uses: actions/setup-node@v3 + uses: actions/setup-node@v4 with: node-version: 20 cache: npm - - name: Install dependencies + + - name: Install npm dependencies run: npm install --dev - - name: Generate documentation + + - name: Build js-doc run: npm run js-doc - - name: Setup mdBook + + # --- mdBook --- + + - name: Set up mdBook uses: peaceiris/actions-mdbook@v2 with: mdbook-version: 'latest' - - run: mdbook build + + - name: Build mdBook + run: mdbook build working-directory: ./docs + + # --- Sphinx --- + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.10' + + - name: Set up Sphinx environment + run: make -C docs setupenv + + - name: Build Sphinx docs + run: make -C docs test diff --git a/.github/workflows/docs-deploy.yml b/.github/workflows/docs-deploy.yml deleted file mode 100644 index f90547e05..000000000 --- a/.github/workflows/docs-deploy.yml +++ /dev/null @@ -1,35 +0,0 @@ -name: Deploy Docs and Book to GitHub Pages - -on: - push: - branches: - - main - -jobs: - build-and-deploy: - runs-on: ubuntu-latest - - steps: - - name: Checkout repository - uses: actions/checkout@v4 - - name: Set up Node.js - uses: actions/setup-node@v3 - with: - node-version: 20 - cache: npm - - name: Install dependencies - run: npm install --dev - - name: Generate documentation - run: npm run js-doc - - name: Setup mdBook - uses: peaceiris/actions-mdbook@v2 - with: - mdbook-version: 'latest' - - run: mdbook build - working-directory: ./docs - - name: Deploy to GitHub Pages - uses: peaceiris/actions-gh-pages@v3 - with: - github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: ./public - publish_branch: gh-pages diff --git a/.github/workflows/docs-pages.yml b/.github/workflows/docs-pages.yml new file mode 100644 index 000000000..b90728616 --- /dev/null +++ b/.github/workflows/docs-pages.yml @@ -0,0 +1,79 @@ +name: "Docs / Publish" +# For more information, +# see https://sphinx-theme.scylladb.com/stable/deployment/production.html#available-workflows + +on: + push: + branches: + - main + - 'branch-**' + paths: + - "docs/**" + workflow_dispatch: + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + ref: ${{ github.event.repository.default_branch }} + persist-credentials: false + fetch-depth: 0 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.10' + + - name: Set up Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + + - name: Set up env + run: make -C docs setupenv + + - name: Build docs + run: make -C docs multiversion + + - name: Build redirects + run: make -C docs redirects + + - name: Tar folder + run: | + tar \ + --dereference --hard-dereference \ + --directory docs/_build/dirhtml/ \ + -cvf ${{ runner.temp }}/artifact.tar \ + . + + - name: Upload artifact + uses: actions/upload-artifact@v4 + with: + name: github-pages + path: ${{ runner.temp }}/artifact.tar + retention-days: "1" + + release: + # Add a dependency to the build job + needs: build + + # Grant GITHUB_TOKEN the permissions required to make a Pages deployment + permissions: + pages: write # to deploy to Pages + id-token: write # to verify the deployment originates from an appropriate source + contents: read # to read private repo + + # Deploy to the github-pages environment + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + # Specify runner + deployment step + runs-on: ubuntu-latest + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index d6c5f974e..a72daa4b1 100644 --- a/.gitignore +++ b/.gitignore @@ -235,3 +235,7 @@ Cargo.lock __pycache__/ *.pyc *.pyo + +#docs +docs/_build +docs/source/api/ diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 000000000..9bb0aee89 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,108 @@ +# Global variables +# You can set these variables from the command line. +POETRY = poetry +SPHINXOPTS = -j auto +SPHINXBUILD = $(POETRY) run sphinx-build +PAPER = +BUILDDIR = _build +SOURCEDIR = source + +# Internal variables +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR) +TESTSPHINXOPTS = $(ALLSPHINXOPTS) -W --keep-going + +.PHONY: all +all: dirhtml + +# Setup commands +.PHONY: setupenv +setupenv: + pip install -q poetry + +.PHONY: setup +setup: + $(POETRY) install + cd .. && npm install + +.PHONY: update +update: + $(POETRY) update + +# Clean commands +.PHONY: pristine +pristine: clean + git clean -dfX + +.PHONY: clean +clean: + rm -rf $(BUILDDIR)/* + rm -rf $(SOURCEDIR)/api + +# Generate output commands +.PHONY: jsdoc +jsdoc: + cd .. && npm run js-doc + @echo + @echo "JSDoc build finished. The API docs are in ../public/docs/." + +.PHONY: api-pages +api-pages: jsdoc + $(POETRY) run python _utils/generate_api_pages.py + +.PHONY: dirhtml +dirhtml: setup api-pages + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +.PHONY: singlehtml +singlehtml: setup + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +.PHONY: epub +epub: setup + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +.PHONY: epub3 +epub3: setup + $(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3 + @echo + @echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3." + +.PHONY: multiversion +multiversion: setup + $(POETRY) run ./_utils/multiversion.sh + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +.PHONY: redirects +redirects: setup + $(POETRY) run redirects-cli fromfile --yaml-file _utils/redirects.yaml --output-dir $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +# Preview commands +.PHONY: preview +preview: setup api-pages + $(POETRY) run sphinx-autobuild -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml --port 5500 + +.PHONY: multiversionpreview +multiversionpreview: multiversion + $(POETRY) run python -m http.server 5500 --directory $(BUILDDIR)/dirhtml + +# Test commands +.PHONY: test +test: setup api-pages + $(SPHINXBUILD) -b dirhtml $(TESTSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +.PHONY: linkcheck +linkcheck: setup + $(SPHINXBUILD) -b linkcheck $(SOURCEDIR) $(BUILDDIR)/linkcheck diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..85e659c86 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,117 @@ +# Documentation + +This directory contains the Sphinx documentation for the ScyllaDB Node.js Driver. + +API reference pages are generated from JSDoc and embedded into Sphinx using a custom extension. + +## Prerequisites + +- Python 3.10+ +- [Poetry](https://python-poetry.org/) +- Node.js and npm (for JSDoc generation) + +## Quick start + +```bash +cd docs +make setupenv # install poetry (once) +make setup # install Python and npm dependencies +make preview # build and serve at http://localhost:5500 +``` + +## Build targets + +| Command | Description | +|---|---| +| `make dirhtml` | Build the HTML documentation | +| `make preview` | Live-reload development server on port 5500 | +| `make test` | Build with `-W` (warnings as errors) | +| `make multiversion` | Build all branches/tags | +| `make clean` | Remove build output | + +## How the API docs work + +The API reference combines two tools: + +1. **JSDoc** generates HTML pages from the JavaScript source code into `public/docs/`. +2. **Sphinx** builds the final documentation site, embedding the JSDoc content via a custom `jsdoc_content` extension. + +### Build pipeline + +``` +npm run js-doc JSDoc HTML files in public/docs/ + | + v +_utils/generate_api_pages.py RST stub files in source/api/ + | + v +sphinx-build Final site in _build/dirhtml/ +``` + +This pipeline runs automatically via `make dirhtml`. You don't need to run individual steps manually. + +### RST page generation (`_utils/generate_api_pages.py`) + +The script reads the `