Add rsync & sphinx-autobuild docs

.github/workflows/build.yml

@@ -468,7 +468,7 @@ jobs:
           name: image-${{ matrix.image_suffix }}
           path: photonvision*.xz
   release:
-    needs: [build-package, build-image]
+    needs: [build-package, build-image, combine]
     runs-on: ubuntu-22.04
     steps:
       # Download all fat JARs

docs/.gitignore

@@ -3,8 +3,6 @@ build/*
 .vscode/*
 .idea/*
 source/_build
-source/_build
-photon-docs/build
 source/docs/_build
 
 venv/*

docs/requirements.txt

@@ -40,3 +40,5 @@ sphinxext-remoteliteralinclude==0.4.0
 stevedore==5.1.0
 urllib3==2.1.0
 yarg==0.1.9
+sphinx-autobuild==2024.4.16
+myst_parser==3.0.1

docs/source/conf.py

@@ -35,6 +35,7 @@
     "sphinxext.opengraph",
     "sphinxcontrib.ghcontributors",
     "sphinx_design",
+    "myst_parser",
 ]
 
 # Configure OpenGraph support
@@ -71,6 +72,7 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
+source_suffix = ['.rst', '.md']
 
 def setup(app):
     app.add_css_file("css/pv-icons.css")

docs/source/docs/contributing/photonvision-docs/building-docs.rst

@@ -17,15 +17,13 @@ You must install a set of Python dependencies in order to build the documentatio
 
 Building the Documentation
 --------------------------
-In order to build the documentation, you can run the following command in the docs sub-folder:
+In order to build the documentation, you can run the following command in the docs sub-folder. This will automatically build docs every time a file changes, and serves them locally at `localhost:8000` by default.
 
-``~/photonvision/docs$ make html``
-
-.. note:: You may have to run ``./make html`` on Windows.
+``~/photonvision/docs$ sphinx-autobuild --open-browser source/_build/html``
 
 Opening the Documentation
 -------------------------
-The built documentation is located at ``docs/build/html/index.html`` relative to the root project directory.
+The built documentation is located at ``docs/build/html/index.html`` relative to the root project directory, or can be accessed via the local web server if using sphinx-autobuild.
 
 Docs Builds on Pull Requests
 ----------------------------

docs/source/docs/developer-docs/index.rst

@@ -0,0 +1,6 @@
+PhotonVision Developer Documentation
+====================================
+
+.. toctree::
+
+    photonlib-backups

docs/source/docs/developer-docs/photonlib-backups.md

@@ -0,0 +1,16 @@
+# Photonlib Developer Docs
+
+Our maven server is located at https://maven.photonvision.org/#/. This server runs [Reposilite](https://hub.docker.com/r/dzikoysk/reposilite) in Docker, and uses Caddy for serving requests.
+
+
+## Backing up using Rsync
+
+The Clarkson Open Source Institute at Clarkson University provides a mirror of our artifacts available [online](https://mirror.clarkson.edu/photonvision). Learn more about them at [their homepage](https://mirror.clarkson.edu/home).
+
+Artifacts from our Maven server can also be backed up locally to a folder called `photonlib-backup` using the following command, which excludes "snapshots" for space reasons:
+
+```
+rsync -avzrHy --no-perms --no-group --no-owner --ignore-errors --exclude ".~tmp~" --exclude "snapshots/org/photonvision/photontargeting*" \
+--exclude "snapshots/org/photonvision/photonlib*" maven.photonvision.org::reposilite-data \
+/path/to/photonlib-packup
+```

docs/source/docs/programming/photonlib/adding-vendordep.rst

@@ -21,8 +21,8 @@ Paste the following URL into the box that pops up:
 
 Offline Install - Java/C++
 --------------------------
-This installation option is currently a work-in-progress. For now, we recommend users use the online installation method.
 
+Download the latest photonlib release from our GitHub releases page, and extract the contents to `$HOME/wpilib/YEAR`.
 Install - Python
 ----------------
 Add photonlibpy to `pyproject.toml`.

docs/source/index.rst

@@ -110,3 +110,10 @@ PhotonVision is licensed under the `GNU GPL v3 <https://www.gnu.org/licenses/gpl
    docs/additional-resources/config
    docs/additional-resources/nt-api
    docs/contributing/index
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Additional Resources
+   :hidden:
+
+   docs/developer-docs/index

photon-docs/README.md

@@ -0,0 +1,3 @@
+# photon-docs
+
+This subproject configures Gradle to build Doxygen & Javadoc HTML documentation for our other subprojects. These are published to https://javadocs.photonvision.org/ and https://cppdocs.photonvision.org/ .