This is an automated email from the ASF dual-hosted git repository.
Gerrrr pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/otava.git
The following commit(s) were added to refs/heads/master by this push:
new da316dd docs: add Sphinx documentation build (#168)
da316dd is described below
commit da316dd2caef3815977b4ea43bf6711b46e47a11
Author: adambernier <[email protected]>
AuthorDate: Sun Aug 30 23:03:53 2026 -0700
docs: add Sphinx documentation build (#168)
---
.github/workflows/python-app.yml | 19 +++++++++++++++
.gitignore | 1 +
.gitignore => .readthedocs.yaml | 23 ++++++++----------
docs/BASICS.md | 4 ++--
docs/README.md | 48 ++++++++++++++++++++++++-------------
docs/RELEASE.md | 4 ++--
.gitignore => docs/conf.py | 23 ++++++++----------
.gitignore => docs/requirements.txt | 19 +++------------
8 files changed, 78 insertions(+), 63 deletions(-)
diff --git a/.github/workflows/python-app.yml b/.github/workflows/python-app.yml
index f23a6e1..0e8faf5 100644
--- a/.github/workflows/python-app.yml
+++ b/.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
diff --git a/.gitignore b/.gitignore
index 7b70f42..5a87371 100644
--- a/.gitignore
+++ b/.gitignore
@@ -31,3 +31,4 @@ dist/
venv/
.tox/
.docker/
+docs/_build/
diff --git a/.gitignore b/.readthedocs.yaml
similarity index 82%
copy from .gitignore
copy to .readthedocs.yaml
index 7b70f42..b5d1822 100644
--- a/.gitignore
+++ b/.readthedocs.yaml
@@ -15,19 +15,16 @@
# specific language governing permissions and limitations
# under the License.
-# IntelliJ IDEA files
-.idea/
-*.iml
+version: 2
-# pyenv version info
-.python-version
+build:
+ os: ubuntu-24.04
+ tools:
+ python: "3.12"
-# Python 3 cache
-__pycache__/
+sphinx:
+ configuration: docs/conf.py
-# Other Python dev dirs
-build/
-dist/
-venv/
-.tox/
-.docker/
+python:
+ install:
+ - requirements: docs/requirements.txt
diff --git a/docs/BASICS.md b/docs/BASICS.md
index b6d7afd..89f64da 100644
--- a/docs/BASICS.md
+++ b/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
-```
\ No newline at end of file
+```
diff --git a/docs/README.md b/docs/README.md
index 37da1c9..4046d93 100644
--- a/docs/README.md
+++ b/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
+```
diff --git a/docs/RELEASE.md b/docs/RELEASE.md
index d8e1103..fe7145c 100644
--- a/docs/RELEASE.md
+++ b/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
diff --git a/.gitignore b/docs/conf.py
similarity index 68%
copy from .gitignore
copy to docs/conf.py
index 7b70f42..5ba1d30 100644
--- a/.gitignore
+++ b/docs/conf.py
@@ -15,19 +15,16 @@
# specific language governing permissions and limitations
# under the License.
-# IntelliJ IDEA files
-.idea/
-*.iml
+project = "Apache Otava (Incubating)"
+copyright = "2026, The Apache Software Foundation"
+author = "The Apache Software Foundation"
-# pyenv version info
-.python-version
+extensions = ["myst_parser"]
+root_doc = "README"
+source_suffix = {".md": "markdown"}
+exclude_patterns = ["_build"]
-# Python 3 cache
-__pycache__/
+myst_enable_extensions = ["colon_fence", "deflist", "dollarmath"]
+myst_heading_anchors = 3
-# Other Python dev dirs
-build/
-dist/
-venv/
-.tox/
-.docker/
+html_theme = "sphinx_rtd_theme"
diff --git a/.gitignore b/docs/requirements.txt
similarity index 82%
copy from .gitignore
copy to docs/requirements.txt
index 7b70f42..954c238 100644
--- a/.gitignore
+++ b/docs/requirements.txt
@@ -15,19 +15,6 @@
# specific language governing permissions and limitations
# under the License.
-# IntelliJ IDEA files
-.idea/
-*.iml
-
-# pyenv version info
-.python-version
-
-# Python 3 cache
-__pycache__/
-
-# Other Python dev dirs
-build/
-dist/
-venv/
-.tox/
-.docker/
+Sphinx>=8.1,<9
+myst-parser>=4,<5
+sphinx-rtd-theme>=3,<4
