Skip to content

Add documentation for python #1887

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.

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
wants to merge 59 commits into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
Show all changes
59 commits
Select commit Hold shift + click to select a range
8452527
Update photon-api-docs.yml
samfreund Apr 12, 2025
c440ce5
Update photon-api-docs.yml
samfreund Apr 12, 2025
35c72e8
Update photon-api-docs.yml
samfreund Apr 12, 2025
47b799a
add docs for python
samfreund Apr 12, 2025
462a2aa
Update photon-api-docs.yml
samfreund Apr 12, 2025
7c6bab1
Update photon-api-docs.yml
samfreund Apr 12, 2025
6d816b5
Update photon-api-docs.yml
samfreund Apr 12, 2025
3c73b68
Update index.md
samfreund Apr 12, 2025
55303cc
Update index.md
samfreund Apr 12, 2025
34057f2
autogen files
samfreund Apr 13, 2025
32e4f00
Merge branch 'py-docs' of github.com:photonvision/photonvision into p…
samfreund Apr 13, 2025
ddacff7
Update photon-api-docs.yml
samfreund Apr 13, 2025
05309b1
Update mkdocs.yml
samfreund Apr 13, 2025
abc67bd
add logo
samfreund Apr 13, 2025
88a1e78
actually add the logo
samfreund Apr 13, 2025
77d5388
Update photon-api-docs.yml
samfreund Apr 13, 2025
e334d26
Update python.yml
samfreund Apr 13, 2025
358f574
man I hate linting
samfreund Apr 13, 2025
871ca61
Merge branch 'main' into py-docs
samfreund Apr 13, 2025
eb85834
add brand color
samfreund Apr 13, 2025
331f4f0
Merge branch 'py-docs' of github.com:photonvision/photonvision into p…
samfreund Apr 13, 2025
d1761d0
update to exclude packet.py
samfreund Apr 13, 2025
228caf4
Update photon-api-docs.yml
samfreund Apr 13, 2025
3cdda8a
Add instructions for excluding a file
samfreund Apr 13, 2025
e522642
linting
samfreund Apr 13, 2025
4081502
Update photon-api-docs.yml
samfreund Apr 13, 2025
3547d05
exclude generated files
samfreund Apr 13, 2025
aacbdf5
Update index.md
samfreund Apr 13, 2025
a5b1cc0
Update photon-api-docs.yml
samfreund Apr 13, 2025
a5bc638
Merge branch 'main' into py-docs
samfreund Apr 13, 2025
ffdda9d
Update photon-api-docs.yml
samfreund Apr 13, 2025
44b46cf
yeah that's good enough
samfreund Apr 14, 2025
0bec1f2
Update photon-api-docs.yml
samfreund Apr 14, 2025
0147a44
remove source
samfreund Apr 14, 2025
3eea79f
Merge branch 'py-docs' of github.com:photonvision/photonvision into p…
samfreund Apr 14, 2025
b22371d
Merge branch 'main' into py-docs
samfreund Apr 15, 2025
abcd6b8
add docs to readme
samfreund May 8, 2025
87b219d
Merge branch 'main' into py-docs
samfreund May 8, 2025
697e52f
lint
samfreund May 8, 2025
96b0938
Merge branch 'py-docs' of github.com:photonvision/photonvision into p…
samfreund May 8, 2025
c2581f3
limit publishing
samfreund May 8, 2025
fa8b60f
convert to requirements.txt
samfreund May 9, 2025
ebd1071
Merge branch 'main' into py-docs
samfreund May 9, 2025
416e2f7
update versions
samfreund May 9, 2025
783ed82
Merge branch 'py-docs' of github.com:photonvision/photonvision into p…
samfreund May 9, 2025
476cd6d
Update photon-api-docs.yml
samfreund May 9, 2025
8fb29ff
Update photon-api-docs.yml
samfreund May 9, 2025
dc0985d
fix docstrings style
samfreund May 9, 2025
cf68403
Merge branch 'py-docs' of github.com:photonvision/photonvision into p…
samfreund May 9, 2025
50adef1
publish release docs
samfreund May 9, 2025
abb8ccf
add conditionals for publishing
samfreund May 9, 2025
26f08a6
switch to sphinx
samfreund May 9, 2025
8cf48be
update requirements.txt
samfreund May 9, 2025
326c77f
dammit, it was a typo
samfreund May 9, 2025
892e240
change theme
samfreund May 9, 2025
6f2fd19
add files to index
samfreund May 9, 2025
1637be6
change path
samfreund May 9, 2025
05fcf87
debugggggging
samfreund May 9, 2025
6fbb41f
this should fix importing?
samfreund May 9, 2025
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
48 changes: 39 additions & 9 deletions .github/workflows/photon-api-docs.yml
Original file line number Diff line number Diff line change
@@ -39,11 +39,11 @@ jobs:
run: npm run build-demo
- uses: actions/upload-artifact@v4
with:
name: built-demo
name: demo
path: photon-client/dist/

run_api_docs:
name: Build API Docs
run_java_cpp_docs:
name: Build Java and C++ API Docs
runs-on: "ubuntu-22.04"
steps:
- name: Checkout code
@@ -63,27 +63,57 @@ jobs:
./gradlew photon-docs:generateJavaDocs photon-docs:doxygen
- uses: actions/upload-artifact@v4
with:
name: built-docs
name: docs-java-cpp
path: photon-docs/build/docs

run_py_docs:
name: Build Python API Docs
runs-on: ubuntu-latest

steps:
- name: Checkout code
uses: actions/checkout@v4

- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.10'

- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install -r photon-lib/py/docs/requirements.txt

- name: Build Sphinx site
run: |
sphinx-apidoc -o docs/source photonlibpy
make -C docs html
working-directory: photon-lib/py

- name: Upload built site as artifact
uses: actions/upload-artifact@v4
with:
name: docs-python
path: photon-lib/py/docs/build/html

publish_api_docs:
name: Publish API Docs
needs: [run_api_docs]
needs: [ run_java_cpp_docs, run_py_docs ]
runs-on: ubuntu-22.04
steps:
# Download docs artifact
- uses: actions/download-artifact@v4
with:
name: built-docs
pattern: docs-*
- run: find .
- name: Publish Docs To Development
if: github.ref == 'refs/heads/main'
# if: github.ref == 'refs/heads/main'
uses: up9cloud/[email protected]
env:
HOST: ${{ secrets.WEBMASTER_SSH_HOST }}
USER: ${{ secrets.WEBMASTER_SSH_USERNAME }}
KEY: ${{secrets.WEBMASTER_SSH_KEY}}
TARGET: /var/www/html/photonvision-docs/development
TARGET: /var/www/html/photonvision-docs/development/
- name: Publish Docs To Release
if: startsWith(github.ref, 'refs/tags/v')
uses: up9cloud/[email protected]
@@ -100,7 +130,7 @@ jobs:
steps:
- uses: actions/download-artifact@v4
with:
name: built-demo
name: demo
- run: find .
- name: Publish demo
if: github.ref == 'refs/heads/main'
2 changes: 1 addition & 1 deletion .github/workflows/python.yml
Original file line number Diff line number Diff line change
@@ -34,7 +34,7 @@ jobs:
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install setuptools wheel pytest mypy
pip install setuptools wheel pytest mypy mkdocs mkdocs-gen-files

- name: Build wheel
working-directory: ./photon-lib/py
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -141,8 +141,12 @@ venv
.venv/*
.venv
networktables.json

# Web stuff
photon-server/src/main/resources/web/*
node_modules
dist
components.d.ts

# Py docs stuff
photon-lib/py/docs/build
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -20,6 +20,7 @@ If you are interested in contributing code or documentation to the project, plea
- Photon UI demo: [http://photonvision.global/](http://photonvision.global/)
- Javadocs: [javadocs.photonvision.org](https://javadocs.photonvision.org)
- C++ Doxygen [cppdocs.photonvision.org](https://cppdocs.photonvision.org)
- Python Documentation [pydocs.photonvision.org](https://pydocs.photonvision.org)

## Building

4 changes: 3 additions & 1 deletion docs/source/index.md
Original file line number Diff line number Diff line change
@@ -137,5 +137,7 @@ docs/contributing/index

Java <https://javadocs.photonvision.org>

C++ <https://cppdocs.photonvision.org/>
C++ <https://cppdocs.photonvision.org>

Python <https://pydocs.photonvision.org>
```
20 changes: 20 additions & 0 deletions photon-lib/py/docs/Makefile
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 photon-lib/py/docs/make.bat
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
@ECHO OFF

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
3 changes: 3 additions & 0 deletions photon-lib/py/docs/requirements.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
sphinx==7.2.6
sphinx-autodoc-typehints==1.25.2
sphinx-rtd-theme==1.3.0
43 changes: 43 additions & 0 deletions photon-lib/py/docs/source/conf.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
import os
import sys

# This adds the 'py/' directory to the Python path
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..')))

# Configuration file for the Sphinx documentation builder.
#
# 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 = "PhotonVision"
copyright = "2025, Matt Morley, Banks Troutman"
author = "Matt Morley, Banks Troutman"

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

extensions = [
"sphinx.ext.autodoc",
"sphinx.ext.napoleon", # for Google/NumPy docstrings
"sphinx_autodoc_typehints", # for type hints in docs
]

import os
import sys

sys.path.insert(
0, os.path.abspath("../../photonlibpy")
) # adjust based on your project layout
print(sys.path)
templates_path = ["_templates"]
exclude_patterns = []

Check failure on line 36 in photon-lib/py/docs/source/conf.py

GitHub Actions / buildAndDeploy

Need type annotation for "exclude_patterns" (hint: "exclude_patterns: list[<type>] = ...")


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

html_theme = "sphinx_rtd_theme"
html_static_path = ["_static"]
17 changes: 17 additions & 0 deletions photon-lib/py/docs/source/index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
.. PhotonVision documentation master file, created by
sphinx-quickstart on Fri May 9 12:16:37 2025.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.

PhotonLib Python Documentation
==========================


The main documentation for PhotonVision can be found at `photonvision.org <https://photonvision.org>`_.

.. toctree::
:maxdepth: 2
:caption: Contents:

modules
photonlibpy # if you have these .rst files from sphinx-apidoc
7 changes: 7 additions & 0 deletions photon-lib/py/docs/source/modules.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
photonlibpy
===========

.. toctree::
:maxdepth: 4

photonlibpy
53 changes: 53 additions & 0 deletions photon-lib/py/docs/source/photonlibpy.estimation.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
photonlibpy.estimation package
==============================

Submodules
----------

photonlibpy.estimation.cameraTargetRelation module
--------------------------------------------------

.. automodule:: photonlibpy.estimation.cameraTargetRelation
:members:
:undoc-members:
:show-inheritance:

photonlibpy.estimation.openCVHelp module
----------------------------------------

.. automodule:: photonlibpy.estimation.openCVHelp
:members:
:undoc-members:
:show-inheritance:

photonlibpy.estimation.rotTrlTransform3d module
-----------------------------------------------

.. automodule:: photonlibpy.estimation.rotTrlTransform3d
:members:
:undoc-members:
:show-inheritance:

photonlibpy.estimation.targetModel module
-----------------------------------------

.. automodule:: photonlibpy.estimation.targetModel
:members:
:undoc-members:
:show-inheritance:

photonlibpy.estimation.visionEstimation module
----------------------------------------------

.. automodule:: photonlibpy.estimation.visionEstimation
:members:
:undoc-members:
:show-inheritance:

Module contents
---------------

.. automodule:: photonlibpy.estimation
:members:
:undoc-members:
:show-inheritance:
61 changes: 61 additions & 0 deletions photon-lib/py/docs/source/photonlibpy.generated.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
photonlibpy.generated package
=============================

Submodules
----------

photonlibpy.generated.MultiTargetPNPResultSerde module
------------------------------------------------------

.. automodule:: photonlibpy.generated.MultiTargetPNPResultSerde
:members:
:undoc-members:
:show-inheritance:

photonlibpy.generated.PhotonPipelineMetadataSerde module
--------------------------------------------------------

.. automodule:: photonlibpy.generated.PhotonPipelineMetadataSerde
:members:
:undoc-members:
:show-inheritance:

photonlibpy.generated.PhotonPipelineResultSerde module
------------------------------------------------------

.. automodule:: photonlibpy.generated.PhotonPipelineResultSerde
:members:
:undoc-members:
:show-inheritance:

photonlibpy.generated.PhotonTrackedTargetSerde module
-----------------------------------------------------

.. automodule:: photonlibpy.generated.PhotonTrackedTargetSerde
:members:
:undoc-members:
:show-inheritance:

photonlibpy.generated.PnpResultSerde module
-------------------------------------------

.. automodule:: photonlibpy.generated.PnpResultSerde
:members:
:undoc-members:
:show-inheritance:

photonlibpy.generated.TargetCornerSerde module
----------------------------------------------

.. automodule:: photonlibpy.generated.TargetCornerSerde
:members:
:undoc-members:
:show-inheritance:

Module contents
---------------

.. automodule:: photonlibpy.generated
:members:
:undoc-members:
:show-inheritance:
21 changes: 21 additions & 0 deletions photon-lib/py/docs/source/photonlibpy.networktables.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
photonlibpy.networktables package
=================================

Submodules
----------

photonlibpy.networktables.NTTopicSet module
-------------------------------------------

.. automodule:: photonlibpy.networktables.NTTopicSet
:members:
:undoc-members:
:show-inheritance:

Module contents
---------------

.. automodule:: photonlibpy.networktables
:members:
:undoc-members:
:show-inheritance:
58 changes: 58 additions & 0 deletions photon-lib/py/docs/source/photonlibpy.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
photonlibpy package
===================

Subpackages
-----------

.. toctree::
:maxdepth: 4

photonlibpy.estimation
photonlibpy.generated
photonlibpy.networktables
photonlibpy.simulation
photonlibpy.targeting
photonlibpy.timesync

Submodules
----------

photonlibpy.estimatedRobotPose module
-------------------------------------

.. automodule:: photonlibpy.estimatedRobotPose
:members:
:undoc-members:
:show-inheritance:

photonlibpy.packet module
-------------------------

.. automodule:: photonlibpy.packet
:members:
:undoc-members:
:show-inheritance:

photonlibpy.photonCamera module
-------------------------------

.. automodule:: photonlibpy.photonCamera
:members:
:undoc-members:
:show-inheritance:

photonlibpy.photonPoseEstimator module
--------------------------------------

.. automodule:: photonlibpy.photonPoseEstimator
:members:
:undoc-members:
:show-inheritance:

Module contents
---------------

.. automodule:: photonlibpy
:members:
:undoc-members:
:show-inheritance:
53 changes: 53 additions & 0 deletions photon-lib/py/docs/source/photonlibpy.simulation.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
photonlibpy.simulation package
==============================

Submodules
----------

photonlibpy.simulation.photonCameraSim module
---------------------------------------------

.. automodule:: photonlibpy.simulation.photonCameraSim
:members:
:undoc-members:
:show-inheritance:

photonlibpy.simulation.simCameraProperties module
-------------------------------------------------

.. automodule:: photonlibpy.simulation.simCameraProperties
:members:
:undoc-members:
:show-inheritance:

photonlibpy.simulation.videoSimUtil module
------------------------------------------

.. automodule:: photonlibpy.simulation.videoSimUtil
:members:
:undoc-members:
:show-inheritance:

photonlibpy.simulation.visionSystemSim module
---------------------------------------------

.. automodule:: photonlibpy.simulation.visionSystemSim
:members:
:undoc-members:
:show-inheritance:

photonlibpy.simulation.visionTargetSim module
---------------------------------------------

.. automodule:: photonlibpy.simulation.visionTargetSim
:members:
:undoc-members:
:show-inheritance:

Module contents
---------------

.. automodule:: photonlibpy.simulation
:members:
:undoc-members:
:show-inheritance:
45 changes: 45 additions & 0 deletions photon-lib/py/docs/source/photonlibpy.targeting.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
photonlibpy.targeting package
=============================

Submodules
----------

photonlibpy.targeting.TargetCorner module
-----------------------------------------

.. automodule:: photonlibpy.targeting.TargetCorner
:members:
:undoc-members:
:show-inheritance:

photonlibpy.targeting.multiTargetPNPResult module
-------------------------------------------------

.. automodule:: photonlibpy.targeting.multiTargetPNPResult
:members:
:undoc-members:
:show-inheritance:

photonlibpy.targeting.photonPipelineResult module
-------------------------------------------------

.. automodule:: photonlibpy.targeting.photonPipelineResult
:members:
:undoc-members:
:show-inheritance:

photonlibpy.targeting.photonTrackedTarget module
------------------------------------------------

.. automodule:: photonlibpy.targeting.photonTrackedTarget
:members:
:undoc-members:
:show-inheritance:

Module contents
---------------

.. automodule:: photonlibpy.targeting
:members:
:undoc-members:
:show-inheritance:
21 changes: 21 additions & 0 deletions photon-lib/py/docs/source/photonlibpy.timesync.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
photonlibpy.timesync package
============================

Submodules
----------

photonlibpy.timesync.timeSyncServer module
------------------------------------------

.. automodule:: photonlibpy.timesync.timeSyncServer
:members:
:undoc-members:
:show-inheritance:

Module contents
---------------

.. automodule:: photonlibpy.timesync
:members:
:undoc-members:
:show-inheritance: