Skip to content

Add initial Sphinx documentation setup with MyST support. #145

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Phanindra899 wants to merge 6 commits into
base: master
Choose a base branch
from
Open

Add initial Sphinx documentation setup with MyST support. #145

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
38f2d14
Add structured documentation homepage replacing directory listing
Phanindra899 Mar 30, 2026
d876ce6
Add documentation landing page replacing directory listing
Phanindra899 Mar 30, 2026
67fc0a9
Add initial Sphinx documentation setup with MyST support
Phanindra899 Mar 30, 2026
9241b07
Ignore Sphinx build and virtual environment files
Phanindra899 Mar 30, 2026
68479e9
Fix Sphinx index to use docs/ as source
Phanindra899 Apr 4, 2026
1f550a4
Clean Sphinx config and add docs path
Phanindra899 Apr 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,3 +31,5 @@ dist/
venv/
.tox/
.docker/
docs_sphinx/venv/
docs_sphinx/build/
100 changes: 100 additions & 0 deletions docs/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
<!DOCTYPE html>
<html lang="en">

<head>
<meta charset="UTF-8">
<title>Apache Otava Documentation</title>

<style>
body {
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Arial, sans-serif;
margin: 0;
background-color: #f6f8fa;
color: #24292e;
}

.container {
max-width: 900px;
margin: 40px auto;
padding: 30px;
background: #ffffff;
border-radius: 10px;
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.05);
}

h1 {
margin-bottom: 10px;
font-size: 28px;
color: #1f2328;
}

p {
color: #57606a;
}

h2 {
margin-top: 30px;
border-bottom: 1px solid #d0d7de;
padding-bottom: 5px;
}

ul {
padding-left: 20px;
}

li {
margin: 8px 0;
}

a {
color: #0969da;
text-decoration: none;
font-weight: 500;
}

a:hover {
text-decoration: underline;
}

.section {
margin-top: 20px;
}
</style>
</head>

<body>
<div class="container">

<h1>Apache Otava Documentation</h1>

<p>
Structured entry point to the Otava documentation, replacing the default directory listing.
</p>

<div class="section">
<h2>Documentation</h2>
<ul>
<li><a href="https://github.com/apache/otava/blob/master/docs/GETTING_STARTED.md">Getting Started</a></li>
<li><a href="https://github.com/apache/otava/blob/master/docs/INSTALL.md">Installation</a></li>
<li><a href="https://github.com/apache/otava/blob/master/docs/BASICS.md">Basics</a></li>
<li><a href="https://github.com/apache/otava/blob/master/docs/MATH.md">Mathematics</a></li>
<li><a href="https://github.com/apache/otava/blob/master/docs/CSV.md">CSV</a></li>
<li><a href="https://github.com/apache/otava/blob/master/docs/BIG_QUERY.md">BigQuery</a></li>
<li><a href="https://github.com/apache/otava/blob/master/docs/POSTGRESQL.md">PostgreSQL</a></li>
<li><a href="https://github.com/apache/otava/blob/master/docs/GRAFANA.md">Grafana</a></li>
<li><a href="https://github.com/apache/otava/blob/master/docs/GRAPHITE.md">Graphite</a></li>
</ul>
</div>

<div class="section">
<h2>Project</h2>
<ul>
<li><a href="https://github.com/apache/otava/blob/master/docs/CONTRIBUTING.md">Contributing</a></li>
<li><a href="https://github.com/apache/otava/blob/master/docs/RELEASE.md">Release Notes</a></li>
</ul>
</div>

</div>
</body>

</html>
20 changes: 20 additions & 0 deletions docs_sphinx/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Minimal makefile for Sphinx documentation
#

# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = source
BUILDDIR = build

# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.PHONY: help Makefile

# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
35 changes: 35 additions & 0 deletions docs_sphinx/make.bat
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
@ECHO OFF
Copy link
Copy Markdown
Contributor

@henrikingo henrikingo Apr 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Interesting. I assume you use Windows? In principle there is no reason to discriminate based on any operating system... But in practice having any part of the build chain using windows BAT files is not going to work, as none of the existing developers could do anything with it.

Are you able to use the Windows Subsystem for Linux? (Despite its name, it really is Linux compatible packages for Windows...) Could you write this same file in SHELL or BASH?

Alternatively you could write this as a python script.


pushd %~dp0

REM Command file for Sphinx documentation

if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=source
set BUILDDIR=build

%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.https://www.sphinx-doc.org/
exit /b 1
)

if "%1" == "" goto help

%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end

:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%

:end
popd
36 changes: 36 additions & 0 deletions docs_sphinx/source/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# Configuration file for the Sphinx documentation builder.
import os
import sys

sys.path.insert(0, os.path.abspath('../..'))

# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = 'otava'
copyright = '2026, Apache Otava'
author = 'Apache Otava'
release = '0.1'

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = ["myst_parser"]

templates_path = ['_templates']
exclude_patterns = []



# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = 'alabaster'
source_suffix = {
".rst": "restructuredtext",
".md": "markdown",
}
html_static_path = ['_static']
18 changes: 18 additions & 0 deletions docs_sphinx/source/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
Welcome to Apache Otava Documentation
====================================

.. toctree::
:maxdepth: 2

../../docs/README.md
../../docs/INSTALL.md
../../docs/GETTING_STARTED.md
../../docs/BASICS.md
../../docs/CSV.md
../../docs/BIG_QUERY.md
../../docs/POSTGRESQL.md
../../docs/GRAFANA.md
../../docs/GRAPHITE.md


This documentation is powered by Sphinx and supports Markdown via MyST.