Add rsync & sphinx-autobuild docs (#1391)

.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 @@ extensions = [
     "sphinxext.opengraph",
     "sphinxcontrib.ghcontributors",
     "sphinx_design",
+    "myst_parser",
 ]
 
 # Configure OpenGraph support
@@ -71,6 +72,8 @@ html_favicon = "assets/RoundLogo.png"
 # 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/building-docs.rst

@@ -17,17 +17,19 @@ 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
 ----------------------------
 
 Pre-merge builds of docs can be found at: ``https://photonvision-docs--PRNUMBER.org.readthedocs.build/en/PRNUMBER/index.html``. These docs are republished on every commit to a pull request made to PhotonVision/photonvision-docs. For example, PR 325 would have pre-merge documentation published to ``https://photonvision-docs--325.org.readthedocs.build/en/325/index.html``. Additionally, the pull requrest will have a link directly to the pre-release build of the docs. This build only runs when there is a change to files in the docs sub-folder.
+
+Style Guide
+-----------
+PhotonVision follows the frc-docs style guide which can be found `here <https://docs.wpilib.org/en/stable/docs/contributing/style-guide.html>`_. In order to run the linter locally (which builds on doc8 and checks for compliance with the style guide), follow the instructions `on GitHub <https://github.com/wpilibsuite/ohnoyoudidnt>`_.

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

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

docs/source/docs/contributing/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-backup
+```

docs/source/docs/contributing/index.rst

@@ -3,5 +3,6 @@ Contributing to PhotonVision Projects
 
 .. toctree::
 
-   photonvision/index
-   photonvision-docs/index
+   building-photon
+   building-docs
+   developer-docs/index

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

@@ -1,8 +0,0 @@
-Contributing to PhotonVision Documentation
-==========================================
-
-.. toctree::
-
-   building-docs
-   style-guide
-   top-contributors

docs/source/docs/contributing/photonvision-docs/style-guide.rst

@@ -1,3 +0,0 @@
-Style Guide
-===========
-PhotonVision follows the frc-docs style guide which can be found `here <https://docs.wpilib.org/en/stable/docs/contributing/style-guide.html>`_. In order to run the linter locally (which builds on doc8 and checks for compliance with the style guide), follow the instructions `on GitHub <https://github.com/wpilibsuite/ohnoyoudidnt>`_.

docs/source/docs/contributing/photonvision-docs/top-contributors.rst

@@ -1,5 +0,0 @@
-Top Contributors
-================
-
-.. ghcontributors:: PhotonVision/photonvision-docs
-   :limit: 10

docs/source/docs/contributing/photonvision/index.rst

@@ -1,7 +0,0 @@
-Contributing to PhotonVision
-============================
-
-.. toctree::
-
-   build-instructions
-   top-contributors

docs/source/docs/contributing/photonvision/top-contributors.rst

@@ -1,5 +0,0 @@
-Top Contributors
-================
-
-.. ghcontributors:: PhotonVision/photonvision
-   :limit: 10

docs/source/docs/installation/updating.rst

@@ -31,7 +31,7 @@ Unless otherwise noted on the release page, config files should be backward comp
 Installing Pre-Release Versions
 -------------------------------
 
-Pre-release/development version of PhotonVision can be tested by installing/downloading artifacts from Github Actions (see below), which are built automatically on commits to open pull requests and to PhotonVision's ``master`` branch, or by :ref:`compiling PhotonVision locally <docs/contributing/photonvision/build-instructions:Build Instructions>`.
+Pre-release/development version of PhotonVision can be tested by installing/downloading artifacts from Github Actions (see below), which are built automatically on commits to open pull requests and to PhotonVision's ``master`` branch, or by :ref:`compiling PhotonVision locally <docs/contributing/building-photon:Build Instructions>`.
 
 .. warning:: If testing a pre-release version of PhotonVision with a robot, PhotonLib must be updated to match the version downloaded! If not, packet schema definitions may not match and unexpected things will occur.
 

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

@@ -19,9 +19,12 @@ Paste the following URL into the box that pops up:
 
 .. note:: It is recommended to Build Robot Code at least once when connected to the Internet before heading to an area where Internet connectivity is limited (for example, a competition). This ensures that the relevant files are downloaded to your filesystem.
 
+Refer to `The WPILib docs <https://docs.wpilib.org/en/stable/docs/software/vscode-overview/3rd-party-libraries.html#installing-libraries>` for more details on installing vendor libraries.
+
 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 (named something like `photonlib-VERSION.zip``), and extract the contents to `$HOME/wpilib/YEAR`. This adds PhotonLib maven artifacts to your local maven repository. PhotonLib will now also appear available in the "install vendor libraries (offline)" menu in WPILib VSCode. Refer to `The WPILib docs <https://docs.wpilib.org/en/stable/docs/software/vscode-overview/3rd-party-libraries.html#installing-libraries>` for more details on installing vendor libraries offline.
 
 Install - Python
 ----------------

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/ .