Skip to content

Commit 26f08a6

Browse files
samfreundsamfreund
committed
switch to sphinx
1 parent abb8ccf commit 26f08a6

21 files changed

+436
-135
lines changed

‎.github/workflows/photon-api-docs.yml

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -84,15 +84,17 @@ jobs:
8484
python -m pip install --upgrade pip
8585
pip install -r photon-lib/py/docs/requirements.txt
8686
87-
- name: Build MkDocs site
88-
run: mkdocs build
87+
- name: Build Sphinx site
88+
run: |
89+
sphinx-apidocs -o docs/source photonlibpy
90+
make -C docs html
8991
working-directory: photon-lib/py
9092

9193
- name: Upload built site as artifact
9294
uses: actions/upload-artifact@v4
9395
with:
9496
name: docs-python
95-
path: photon-lib/py/site/
97+
path: photon-lib/py/docs/build/html
9698

9799
publish_api_docs:
98100
name: Publish API Docs
@@ -105,7 +107,7 @@ jobs:
105107
pattern: docs-*
106108
- run: find .
107109
- name: Publish Docs To Development
108-
if: github.ref == 'refs/heads/main'
110+
# if: github.ref == 'refs/heads/main'
109111
uses: up9cloud/[email protected]
110112
env:
111113
HOST: ${{ secrets.WEBMASTER_SSH_HOST }}

‎.gitignore

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -149,5 +149,4 @@ dist
149149
components.d.ts
150150

151151
# Py docs stuff
152-
photon-lib/py/site
153-
photon-lib/py/docs/reference
152+
photon-lib/py/docs/build

‎photon-lib/py/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)

‎photon-lib/py/docs/SUMMARY.md

Lines changed: 0 additions & 24 deletions
This file was deleted.

‎photon-lib/py/docs/index.md

Lines changed: 0 additions & 3 deletions
This file was deleted.

‎photon-lib/py/docs/logo.svg

Lines changed: 0 additions & 23 deletions
This file was deleted.

‎photon-lib/py/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

‎photon-lib/py/docs/requirements.txt

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,4 @@
1-
mkdocs==1.6.1
2-
mkdocs-material==9.6.12
3-
mkdocstrings[python]==0.29.1
4-
mkdocs-gen-files==0.5.0
5-
mkdocs-literate-nav==0.6.2
6-
mkdocs-section-index==0.3.10
7-
mkdocs-exclude==1.0.2
1+
sphinx==7.2.6
2+
sphinx-autodoc-typehints==1.25.2
3+
sphinx-rtd-theme==1.3.0
4+
sphinx-apidoc==1.0.0

‎photon-lib/py/docs/source/conf.py

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
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+
9+
project = "PhotonVision"
10+
copyright = "2025, Matt Morley, Banks Troutman"
11+
author = "Matt Morley, Banks Troutman"
12+
13+
# -- General configuration ---------------------------------------------------
14+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
15+
16+
extensions = [
17+
"sphinx.ext.autodoc",
18+
"sphinx.ext.napoleon", # for Google/NumPy docstrings
19+
"sphinx_autodoc_typehints", # for type hints in docs
20+
]
21+
22+
import os
23+
import sys
24+
25+
sys.path.insert(0, os.path.abspath("../..")) # adjust based on your project layout
26+
27+
templates_path = ["_templates"]
28+
exclude_patterns = []
29+
30+
31+
# -- Options for HTML output -------------------------------------------------
32+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
33+
34+
html_theme = "alabaster"
35+
html_static_path = ["_static"]

‎photon-lib/py/docs/source/index.rst

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
.. PhotonVision documentation master file, created by
2+
sphinx-quickstart on Fri May 9 12:16:37 2025.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
PhotonVision 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)