Skip to content

Commit f2198ab

Browse files
DanielAvdarDanielAvdar
authored
Merge pull request #9 from DanielAvdar/docs-dbot
Add Sphinx documentation and related configuration
2 parents 1423e53 + 17aa151 commit f2198ab

14 files changed

Lines changed: 861 additions & 155 deletions

File tree

‎.github/dependabot.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,10 @@ updates:
99
directory: "/" # Location of package manifests
1010
schedule:
1111
interval: daily
12+
- package-ecosystem: "uv" # See documentation for possible values
13+
directory: "/" # Location of package manifests
14+
schedule:
15+
interval: daily
1216
- package-ecosystem: "github-actions"
1317
directory: "/"
1418
schedule:

‎.github/workflows/codecov.yml‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
name: Codecov
2+
on:
3+
pull_request:
4+
paths:
5+
- 'my_pkg/**' # todo: change my_pkg to the name of the package
6+
- 'tests/**'
7+
- '.github/workflows/codecov.yml'
8+
push:
9+
branches:
10+
- main
11+
workflow_dispatch:
12+
jobs:
13+
upload-coverage-report:
14+
runs-on: ubuntu-latest
15+
steps:
16+
- uses: actions/checkout@v4
17+
- uses: astral-sh/setup-uv@v4
18+
with:
19+
enable-cache: true
20+
- run: uv python install 3.11
21+
- run: make
22+
- run: make coverage
23+
- uses: codecov/codecov-action@v4
24+
with:
25+
fail_ci_if_error: true
26+
verbose: true
27+
env:
28+
CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
29+
- uses: codecov/test-results-action@v1
30+
with:
31+
token: ${{ secrets.CODECOV_TOKEN }}

‎.github/workflows/docs.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
name: Publish docs GH Pages
2+
on:
3+
pull_request: # todo: remove this after testing
4+
release:
5+
types: [ published ]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: write
10+
pages: write
11+
id-token: write
12+
13+
jobs:
14+
15+
create-docs:
16+
runs-on: ubuntu-latest
17+
18+
steps:
19+
- uses: actions/checkout@v4
20+
- uses: astral-sh/setup-uv@v5
21+
with:
22+
enable-cache: true
23+
- run: uv python install 3.11
24+
25+
- run: make
26+
- run: make doc
27+
28+
- name: Deploy
29+
uses: peaceiris/actions-gh-pages@v4
30+
with:
31+
github_token: ${{ secrets.GITHUB_TOKEN }}
32+
publish_dir: ./docs/build
33+
keep_files: true

‎.pre-commit-config.yaml‎

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,14 +7,9 @@ repos:
77
- id: trailing-whitespace
88
- id: no-commit-to-branch
99
- repo: https://github.com/astral-sh/ruff-pre-commit
10-
rev: v0.8.4
10+
rev: v0.11.4
1111
hooks:
1212
- id: ruff-format
1313
args: [ --preview, --config=pyproject.toml ]
1414
- id: ruff
1515
args: [ --preview, --fix,--unsafe-fixes, --config=pyproject.toml ]
16-
17-
- repo: https://github.com/astral-sh/uv-pre-commit
18-
rev: 0.5.13
19-
hooks:
20-
- id: uv-lock

‎.readthedocs.yaml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Read the Docs configuration file
2+
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
3+
4+
# Required
5+
version: 2
6+
7+
# Build documentation in the "docs/" directory with Sphinx
8+
9+
sphinx:
10+
configuration: docs/source/conf.py
11+
# Optionally build your docs in additional formats such as PDF and ePub
12+
formats: all
13+
14+
# Set the OS, Python version, and other tools you might need
15+
build:
16+
os: ubuntu-24.04
17+
tools:
18+
python: "3.12"
19+
jobs:
20+
post_install:
21+
- pip install uv
22+
- UV_PROJECT_ENVIRONMENT=$READTHEDOCS_VIRTUALENV_PATH uv sync --all-extras --group docs --link-mode=copy

‎Makefile‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,10 @@ check:
1919
uv run pre-commit run --all-files
2020

2121
coverage:
22-
uv run pytest --cov=ml_orchestrator --cov-report=xml
22+
uv run pytest --cov=my_pkg --cov-report=xml # todo: change my_pkg to the actual package name
2323

2424
mypy:
25-
uv tool run mypy . --config-file pyproject.toml
25+
uv tool run mypy my_pkg --config-file pyproject.toml # todo: chanege my_pkg to the actual package name
26+
27+
doc:
28+
uv run sphinx-build -M html docs/source docs/build/

‎docs/Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = source
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/make.bat‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=source
11+
set BUILDDIR=build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎docs/source/conf.py‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
6+
# -- Project information -----------------------------------------------------
7+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
8+
import os
9+
import sys
10+
from importlib.metadata import version
11+
12+
sys.path.insert(0, os.path.abspath("../../"))
13+
# sys.path.insert(0, os.path.abspath("./")) # in conf.py
14+
15+
16+
project = "python-template" # todo: change this to your project name
17+
version = version("my-pkg") # todo: change my-pkg to your package name
18+
release = version
19+
20+
copyright = "2025, DanielAvdar" # noqa todo: change this to your name
21+
author = "DanielAvdar" # todo: change this to your name
22+
23+
# -- General configuration ---------------------------------------------------
24+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
25+
26+
extensions = [
27+
"sphinx.ext.autodoc", # Core extension for pulling docstrings
28+
"sphinx.ext.napoleon", # Support for Google and NumPy style docstrings
29+
"sphinx.ext.viewcode", # Add links to source code
30+
"sphinx.ext.githubpages", # If deploying to GitHub Pages
31+
"sphinx.ext.autodoc",
32+
"sphinx.ext.doctest",
33+
"sphinx.ext.intersphinx",
34+
]
35+
36+
templates_path = ["_templates"]
37+
exclude_patterns = []
38+
39+
40+
# -- Options for HTML output -------------------------------------------------
41+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
42+
43+
html_theme = "sphinx_rtd_theme"
44+
master_doc = "index"
45+
html_static_path = ["_static"]

‎docs/source/index.rst‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
.. python-template documentation master file, created by
2+
sphinx-quickstart on Wed Apr 9 13:29:29 2025.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
python-template documentation
7+
=============================
8+
9+
Add your content using ``reStructuredText`` syntax. See the
10+
`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
11+
documentation for details.
12+
13+
14+
.. toctree::
15+
:maxdepth: 2
16+
:caption: Contents:

0 commit comments

Comments
 (0)