From ad90c29c11154a4a843585ecf4be9433a4b87e95 Mon Sep 17 00:00:00 2001 From: Adam Bernier Date: Sun, 9 Aug 2026 08:32:47 -0700 Subject: [PATCH] docs: add Sphinx documentation build --- .github/workflows/python-app.yml | 19 +++++++++++++ .gitignore | 1 + .readthedocs.yaml | 30 ++++++++++++++++++++ docs/BASICS.md | 4 +-- docs/README.md | 48 +++++++++++++++++++++----------- docs/RELEASE.md | 4 +-- docs/conf.py | 30 ++++++++++++++++++++ docs/requirements.txt | 20 +++++++++++++ 8 files changed, 135 insertions(+), 21 deletions(-) create mode 100644 .readthedocs.yaml create mode 100644 docs/conf.py create mode 100644 docs/requirements.txt diff --git a/.github/workflows/python-app.yml b/.github/workflows/python-app.yml index f23a6e1e..0e8faf50 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 7b70f428..5a873716 100644 --- a/.gitignore +++ b/.gitignore @@ -31,3 +31,4 @@ dist/ venv/ .tox/ .docker/ +docs/_build/ diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..b5d18220 --- /dev/null +++ b/.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 diff --git a/docs/BASICS.md b/docs/BASICS.md index b6d7afdf..89f64daa 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 37da1c99..4046d934 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 d8e11035..fe7145c8 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/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..5ba1d30f --- /dev/null +++ b/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" diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..954c2383 --- /dev/null +++ b/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