diff --git a/.github/workflows/photon-api-docs.yml b/.github/workflows/photon-api-docs.yml index b02f290d6a..0f3de5cae7 100644 --- a/.github/workflows/photon-api-docs.yml +++ b/.github/workflows/photon-api-docs.yml @@ -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/action-rsync@v1.4 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/action-rsync@v1.4 @@ -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' diff --git a/.github/workflows/python.yml b/.github/workflows/python.yml index ddb5bf4d38..c56eb96fda 100644 --- a/.github/workflows/python.yml +++ b/.github/workflows/python.yml @@ -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 diff --git a/.gitignore b/.gitignore index 63d518c8da..920c550086 100644 --- a/.gitignore +++ b/.gitignore @@ -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 diff --git a/README.md b/README.md index ff82034b26..fe6ddf6171 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/source/index.md b/docs/source/index.md index 6a6d01a4b5..5672990e1a 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -137,5 +137,7 @@ docs/contributing/index Java - C++ + C++ + + Python ``` diff --git a/photon-lib/py/docs/Makefile b/photon-lib/py/docs/Makefile new file mode 100644 index 0000000000..d0c3cbf102 --- /dev/null +++ b/photon-lib/py/docs/Makefile @@ -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) diff --git a/photon-lib/py/docs/make.bat b/photon-lib/py/docs/make.bat new file mode 100644 index 0000000000..dc1312ab09 --- /dev/null +++ b/photon-lib/py/docs/make.bat @@ -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 diff --git a/photon-lib/py/docs/requirements.txt b/photon-lib/py/docs/requirements.txt new file mode 100644 index 0000000000..a50ed8933e --- /dev/null +++ b/photon-lib/py/docs/requirements.txt @@ -0,0 +1,3 @@ +sphinx==7.2.6 +sphinx-autodoc-typehints==1.25.2 +sphinx-rtd-theme==1.3.0 diff --git a/photon-lib/py/docs/source/conf.py b/photon-lib/py/docs/source/conf.py new file mode 100644 index 0000000000..3ae4477506 --- /dev/null +++ b/photon-lib/py/docs/source/conf.py @@ -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 = [] + + +# -- 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"] diff --git a/photon-lib/py/docs/source/index.rst b/photon-lib/py/docs/source/index.rst new file mode 100644 index 0000000000..c388e49886 --- /dev/null +++ b/photon-lib/py/docs/source/index.rst @@ -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 `_. + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + modules + photonlibpy # if you have these .rst files from sphinx-apidoc diff --git a/photon-lib/py/docs/source/modules.rst b/photon-lib/py/docs/source/modules.rst new file mode 100644 index 0000000000..486e417877 --- /dev/null +++ b/photon-lib/py/docs/source/modules.rst @@ -0,0 +1,7 @@ +photonlibpy +=========== + +.. toctree:: + :maxdepth: 4 + + photonlibpy diff --git a/photon-lib/py/docs/source/photonlibpy.estimation.rst b/photon-lib/py/docs/source/photonlibpy.estimation.rst new file mode 100644 index 0000000000..05004e2f41 --- /dev/null +++ b/photon-lib/py/docs/source/photonlibpy.estimation.rst @@ -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: diff --git a/photon-lib/py/docs/source/photonlibpy.generated.rst b/photon-lib/py/docs/source/photonlibpy.generated.rst new file mode 100644 index 0000000000..bc21eb9fab --- /dev/null +++ b/photon-lib/py/docs/source/photonlibpy.generated.rst @@ -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: diff --git a/photon-lib/py/docs/source/photonlibpy.networktables.rst b/photon-lib/py/docs/source/photonlibpy.networktables.rst new file mode 100644 index 0000000000..88327af972 --- /dev/null +++ b/photon-lib/py/docs/source/photonlibpy.networktables.rst @@ -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: diff --git a/photon-lib/py/docs/source/photonlibpy.rst b/photon-lib/py/docs/source/photonlibpy.rst new file mode 100644 index 0000000000..8d14d19830 --- /dev/null +++ b/photon-lib/py/docs/source/photonlibpy.rst @@ -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: diff --git a/photon-lib/py/docs/source/photonlibpy.simulation.rst b/photon-lib/py/docs/source/photonlibpy.simulation.rst new file mode 100644 index 0000000000..4d691df70a --- /dev/null +++ b/photon-lib/py/docs/source/photonlibpy.simulation.rst @@ -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: diff --git a/photon-lib/py/docs/source/photonlibpy.targeting.rst b/photon-lib/py/docs/source/photonlibpy.targeting.rst new file mode 100644 index 0000000000..2619708e17 --- /dev/null +++ b/photon-lib/py/docs/source/photonlibpy.targeting.rst @@ -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: diff --git a/photon-lib/py/docs/source/photonlibpy.timesync.rst b/photon-lib/py/docs/source/photonlibpy.timesync.rst new file mode 100644 index 0000000000..5c111332f4 --- /dev/null +++ b/photon-lib/py/docs/source/photonlibpy.timesync.rst @@ -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: