docs: add Sphinx documentation build

.github/workflows/python-app.yml

@@ -59,6 +59,25 @@ jobs:
       - name: Run tox
         run: tox -e py
 
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          python-version: "3.12"
+          prune-cache: true
+
+      - name: Build documentation
+        run: uv run --with-requirements docs/requirements.txt sphinx-build -W --keep-going -b html docs docs/_build/html
+
   docker-build:
     runs-on: ubuntu-latest
     needs: build

.gitignore

@@ -31,3 +31,4 @@ dist/
 venv/
 .tox/
 .docker/
+docs/_build/

.readthedocs.yaml

@@ -0,0 +1,30 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - requirements: docs/requirements.txt

docs/BASICS.md

@@ -79,7 +79,7 @@ The results are simply concatenated.
 
 > [!TIP]
 > See [otava.yaml](../examples/csv/config/otava.yaml) for the full
-> example configuration and [local_samples.csv](../examples/csv/data/local_samples.csv)
+> example configuration and [local_sample.csv](../examples/csv/data/local_sample.csv)
 > for the data.
 
 ```
@@ -223,4 +223,4 @@ The `--branch` option can also be set via the `BRANCH` environment variable:
 
 ```
 BRANCH=feature-xyz otava analyze my-product.test
-```
+```

docs/README.md

@@ -17,20 +17,34 @@
  under the License.
  -->
 
-# Table of Contents
-
-## Getting Started
-- [Installation](INSTALL.md)
-- [Getting Started](GETTING_STARTED.md)
-- [Contributing](CONTRIBUTING.md)
-
-## Basics
-- [Basics](BASICS.md)
-
-## Data Sources
-- [Graphite](GRAPHITE.md)
-- [PostgreSQL](POSTGRESQL.md)
-- [BigQuery](BIG_QUERY.md)
-- [CSV](CSV.md)
-- [InfluxDB](INFLUXDB.md)
-- [Annotating Change Points in Grafana](GRAFANA.md)
+# Apache Otava Documentation
+
+```{toctree}
+:maxdepth: 2
+:caption: Getting Started
+
+INSTALL
+GETTING_STARTED
+CONTRIBUTING
+```
+
+```{toctree}
+:maxdepth: 2
+:caption: Using Otava
+
+BASICS
+CSV
+GRAPHITE
+POSTGRESQL
+BIG_QUERY
+INFLUXDB
+GRAFANA
+```
+
+```{toctree}
+:maxdepth: 2
+:caption: Reference
+
+MATH
+RELEASE
+```

docs/RELEASE.md

@@ -39,7 +39,7 @@ Please remember, that the act of publishing software has both legal and policy s
 ### What is in Apache Otava Release
 
 Apache Otava release consists of:
-* ASF source zips archived on [dist.apache.org](dist.apache.org).
+* ASF source zips archived on [dist.apache.org](https://dist.apache.org).
 * PyPI wheels published to [pypi.org](https://pypi.org/project/apache-otava/).
 * Docker images published to [Dockerhub](https://hub.docker.com/r/apache/otava).
 * Release tag on [GitHub](https://github.com/apache/otava/releases).
@@ -64,7 +64,7 @@ Deciding to release and selecting a Release Manager is the first step of the rel
 Anybody can propose a release on the dev@ mailing list, giving a solid argument and nominating a committer as the Release Manager (including themselves). There’s no formal process, no vote requirements, and no timing requirements. Any objections should be resolved by consensus before starting the release.
 In general, the community prefers to have a rotating set of 3-5 Release Managers. Keeping a small core set of managers allows enough people to build expertise in this area and improve processes over time, without Release Managers needing to re-learn the processes for each release. That said, if you are a committer interested in serving the community in this way, please reach out to the community on the dev@ mailing list.
 
-#### Checklist to proceed to the next step
+### Checklist to proceed to the next step
 
 1. Community agrees to release
 2. Community selects a Release Manager

docs/conf.py

@@ -0,0 +1,30 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+project = "Apache Otava (Incubating)"
+copyright = "2026, The Apache Software Foundation"
+author = "The Apache Software Foundation"
+
+extensions = ["myst_parser"]
+root_doc = "README"
+source_suffix = {".md": "markdown"}
+exclude_patterns = ["_build"]
+
+myst_enable_extensions = ["colon_fence", "deflist", "dollarmath"]
+myst_heading_anchors = 3
+
+html_theme = "sphinx_rtd_theme"

docs/requirements.txt

@@ -0,0 +1,20 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+Sphinx>=8.1,<9
+myst-parser>=4,<5
+sphinx-rtd-theme>=3,<4