Skip to content

docs: add Sphinx documentation site with user and contributor guides#24

Merged
andygrove merged 21 commits into
apache:mainfrom
andygrove:worktree-docs-site
May 13, 2026
Merged

docs: add Sphinx documentation site with user and contributor guides#24
andygrove merged 21 commits into
apache:mainfrom
andygrove:worktree-docs-site

Conversation

@andygrove
Copy link
Copy Markdown
Member

Summary

Add a Sphinx-based documentation site under docs/, mirroring the layout used by sibling DataFusion subprojects (datafusion, datafusion-comet, datafusion-python).

What changed

  • New docs/ directory with Sphinx config (source/conf.py), MyST parser for Markdown, pydata-sphinx-theme, and build.sh/Makefile/make.bat scaffolding.
  • Landing page (docs/source/index.md) with the Quickstart example and three toctrees (Links, User Guide, Contributor Guide).
  • User guide (docs/source/user-guide/): installation, quickstart walkthrough, SessionContext lifecycle and threading, DataFrame + SQL API, Parquet ingestion with ParquetReadOptions, project status checklists.
  • Contributor guide (docs/source/contributor-guide/): build & test workflow, code style (spotless, cargo fmt/clippy, license headers), DataFusion / protobuf version bump recipe, releasing placeholder.
  • Trim root README.md to a slim Quickstart + pointers into the docs site.
  • Add a slim CONTRIBUTING.md pointing to the contributor guide.
  • .gitignore excludes docs/build/ and docs/venv/.

Build

cd docs
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
./build.sh

build.sh uses -W so any future Sphinx warning fails the build. Site builds cleanly today with zero warnings.

Not in this PR

  • Javadoc / API reference generation.
  • GitHub Actions publish workflow / ASF site target.
  • Logo asset and visual branding.
  • Multi-version docs.

@andygrove andygrove merged commit f61b10f into apache:main May 13, 2026
1 check passed
@andygrove andygrove deleted the worktree-docs-site branch May 13, 2026 13:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant