Add documentation for python

.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,18 +63,46 @@ 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 mkdocs mkdocs-material mkdocstrings[python] mkdocs-gen-files mkdocs-literate-nav mkdocs-section-index mkdocs-exclude
+
+      - name: Build MkDocs site
+        run: mkdocs build
+        working-directory: photon-lib/py
+
+      - name: Upload built site as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-python
+          path: photon-lib/py/site/
+
   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'
@@ -100,7 +128,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'

.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

.gitignore

@@ -141,8 +141,13 @@ 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/site
+photon-lib/py/docs/reference

README.md

@@ -20,7 +20,7 @@ If you are interested in contributing code or documentation to the project, plea
 - Photon UI demo: [http://photonvision.global/](http://photonvision.global/) (or [manual link](https://photonvision.github.io/photonvision/built-client/))
 - Javadocs: [javadocs.photonvision.org](https://javadocs.photonvision.org) (or [manual link](https://photonvision.github.io/photonvision/built-docs/javadoc/))
 - C++ Doxygen  [cppdocs.photonvision.org](https://cppdocs.photonvision.org) (or [manual link](https://photonvision.github.io/photonvision/built-docs/doxygen/html/))
-
+- Python Documentation [pydocs.photonvision.org](https://pydocs.photonvision.org)
 ## Building
 
 Gradle is used for all C++ and Java code, and NPM is used for the web UI. Instructions to compile PhotonVision yourself can be found [in our docs](https://docs.photonvision.org/en/latest/docs/contributing/building-photon.html#compiling-instructions).

docs/source/index.md

@@ -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>
 ```

photon-lib/py/docs/SUMMARY.md

@@ -0,0 +1,24 @@
+* [estimatedRobotPose](reference/estimatedRobotPose.md)
+* estimation
+    * [cameraTargetRelation](reference/estimation/cameraTargetRelation.md)
+    * [openCVHelp](reference/estimation/openCVHelp.md)
+    * [rotTrlTransform3d](reference/estimation/rotTrlTransform3d.md)
+    * [targetModel](reference/estimation/targetModel.md)
+    * [visionEstimation](reference/estimation/visionEstimation.md)
+* networktables
+    * [NTTopicSet](reference/networktables/NTTopicSet.md)
+* [photonCamera](reference/photonCamera.md)
+* [photonPoseEstimator](reference/photonPoseEstimator.md)
+* simulation
+    * [photonCameraSim](reference/simulation/photonCameraSim.md)
+    * [simCameraProperties](reference/simulation/simCameraProperties.md)
+    * [videoSimUtil](reference/simulation/videoSimUtil.md)
+    * [visionSystemSim](reference/simulation/visionSystemSim.md)
+    * [visionTargetSim](reference/simulation/visionTargetSim.md)
+* targeting
+    * [TargetCorner](reference/targeting/TargetCorner.md)
+    * [multiTargetPNPResult](reference/targeting/multiTargetPNPResult.md)
+    * [photonPipelineResult](reference/targeting/photonPipelineResult.md)
+    * [photonTrackedTarget](reference/targeting/photonTrackedTarget.md)
+* timesync
+    * [timeSyncServer](reference/timesync/timeSyncServer.md)

photon-lib/py/docs/index.md

@@ -0,0 +1,3 @@
+# PhotonLib Python Docs
+
+For the full PhotonVision documentation visit [docs.photonvision.org](https://docs.photonvision.org).

photon-lib/py/docs/stylesheets/extra.css

@@ -0,0 +1,3 @@
+:root  > * {
+  --md-primary-fg-color:        #3498DB;
+}

photon-lib/py/gen_api_docs.py

@@ -0,0 +1,29 @@
+# gen_api_docs.py
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()
+
+for path in sorted(Path("photonlibpy").rglob("*.py")):
+    if path.name == "py.typed":
+        continue
+
+    module_path = path.with_suffix("").as_posix().replace("/", ".")
+    parts = tuple(path.relative_to("photonlibpy").with_suffix("").parts)
+
+    if path.name == "__init__.py":
+        continue
+    else:
+        doc_path = Path("reference", *parts).with_suffix(".md")
+
+    nav[parts] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(doc_path, "w") as f:
+        f.write(f"# `{module_path}`\n\n::: {module_path}")
+
+    mkdocs_gen_files.set_edit_path(doc_path, path)
+
+with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())

photon-lib/py/mkdocs.yml

@@ -0,0 +1,39 @@
+site_name: PhotonLibPy Docs
+theme:
+  name: material
+  favicon: docs/favicon.ico  # If you want a favicon
+  logo: logo.svg        # Optional logo
+  palette:
+    primary: custom
+
+plugins:
+  - search:
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            show_source: false
+          paths:
+            - "."
+  - gen-files:
+      scripts:
+        - gen_api_docs.py
+  - literate-nav
+  - section-index
+  # To exclude files, add them under glob using their
+  # path from photonlibpy prepended by reference/
+  # Additionally, change the extension from .py to .md
+  - exclude:
+      glob:
+        - "reference/packet.md"
+        - "reference/generated/*"
+
+nav:
+  - Home: index.md
+  - Reference: reference/SUMMARY.md
+
+extra_css:
+  - stylesheets/extra.css
+
+extra_javascript:
+  - js/exclude-details.js