Migration guide

Migrate from Sphinx doctest to DocsCI

Sphinx doctest runs Python >>> prompts embedded in RST files. DocsCI replaces and extends this: it executes Python snippets in an isolated WASM sandbox, adds JavaScript/TypeScript/Go/curl support, detects API drift, and posts PR comments with AI fixes. You keep your RST files exactly as they are.

Zero doc changes required. DocsCI parses your existing RST fenced code blocks. You don't need to reformat existing doctests — DocsCI recognizes Python prompts and interactive sessions.

What changes

Sphinx doctest	DocsCI
Python only	Python, JS, TS, Go, Ruby, curl, Bash
RST + doctest directive required	Any RST, Markdown, MDX, AsciiDoc
In-process execution	Isolated V8 / WASM sandbox
CI via Sphinx build step	Single curl call or GitHub Action
Build logs only on failure	Inline PR comments with AI fixes
No secret scanning	40+ patterns before execution
No API drift detection	OpenAPI spec vs docs diff

Migration steps

Sign up and get a token

Create an account at snippetci.com/signup, create a project, and generate an API token from Settings → Tokens.

Add docsci.yml to your repo root

Create a docsci.yml to configure DocsCI to scan your RST files:

# docsci.yml — add to your repo root
docs:
  path: .
  include:
    - "docs/**/*.rst"
    - "docs/**/*.md"
    - "*.rst"
  exclude:
    - "docs/_build/**"
    - "**/_static/**"

snippets:
  languages: [python, javascript, typescript, bash, curl]
  timeout_seconds: 20
  skip_patterns:
    - "# doctest: +SKIP"
    - "# docsci-skip"
    - "EXPECTED OUTPUT"

checks:
  snippets: true
  accessibility: true
  copy_lint: true
  drift: false   # enable when you have an OpenAPI spec

Add the GitHub Action

Create the workflow file — it runs DocsCI alongside (or instead of) your existing Sphinx build:

# .github/workflows/docsci.yml
name: DocsCI (replacing Sphinx doctest)

on:
  push:
    branches: [main, master]
  pull_request:
    paths:
      - 'docs/**'
      - '*.rst'
      - '*.md'

jobs:
  docs-ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # Keep your existing Sphinx build — DocsCI runs alongside it
      - name: Build Sphinx docs (optional)
        run: |
          pip install sphinx 2>/dev/null || true
          make -C docs html 2>/dev/null || true

      - name: Run DocsCI
        run: |
          tar czf docs.tar.gz docs/ *.rst 2>/dev/null || tar czf docs.tar.gz docs/
          curl -sf -X POST https://snippetci.com/api/runs/queue \
            -H "Authorization: Bearer ${{ secrets.DOCSCI_TOKEN }}" \
            -F "docs_archive=@docs.tar.gz" \
          | jq -e '.status == "passed"'

Mark intentionally-failing examples

For doctest examples that are intentionally invalid (showing error states), add a skip comment above the block:

# docsci-skip
```python
raise ValueError("Expected error")
```

Or configure skip_patterns in docsci.yml to match your existing doctest skip markers.

Remove or disable Sphinx doctest (optional)

Once DocsCI is passing in CI, you can remove the Sphinx doctest step from your Makefile and CI. Keep Sphinx for building the HTML docs — DocsCI only replaces the test step.

Run both in parallel first. During the transition sprint, keep Sphinx doctest running alongside DocsCI. Once DocsCI is catching everything Sphinx caught (and more), remove the Sphinx step.

GitHub Actions →DocsCI vs Sphinx doctest →