diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 6f96710a46..b4d49323c0 100644 --- a/.github/workflows/build.yml +++ b/.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 diff --git a/docs/.gitignore b/docs/.gitignore index f79cf99890..b7a9f77acb 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -3,8 +3,6 @@ build/* .vscode/* .idea/* source/_build -source/_build -photon-docs/build source/docs/_build venv/* diff --git a/docs/requirements.txt b/docs/requirements.txt index 582e43a6c3..84c1582463 100644 --- a/docs/requirements.txt +++ b/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 diff --git a/docs/source/conf.py b/docs/source/conf.py index cfc08effe9..48c878bdf6 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -35,6 +35,7 @@ "sphinxext.opengraph", "sphinxcontrib.ghcontributors", "sphinx_design", + "myst_parser", ] # Configure OpenGraph support @@ -71,6 +72,8 @@ # 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") diff --git a/docs/source/docs/contributing/photonvision/assets/git-download.png b/docs/source/docs/contributing/assets/git-download.png similarity index 100% rename from docs/source/docs/contributing/photonvision/assets/git-download.png rename to docs/source/docs/contributing/assets/git-download.png diff --git a/docs/source/docs/contributing/photonvision-docs/building-docs.rst b/docs/source/docs/contributing/building-docs.rst similarity index 71% rename from docs/source/docs/contributing/photonvision-docs/building-docs.rst rename to docs/source/docs/contributing/building-docs.rst index 3133721245..d3da03b0a4 100644 --- a/docs/source/docs/contributing/photonvision-docs/building-docs.rst +++ b/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 `_. In order to run the linter locally (which builds on doc8 and checks for compliance with the style guide), follow the instructions `on GitHub `_. diff --git a/docs/source/docs/contributing/photonvision/build-instructions.rst b/docs/source/docs/contributing/building-photon.rst similarity index 100% rename from docs/source/docs/contributing/photonvision/build-instructions.rst rename to docs/source/docs/contributing/building-photon.rst diff --git a/docs/source/docs/contributing/developer-docs/index.rst b/docs/source/docs/contributing/developer-docs/index.rst new file mode 100644 index 0000000000..3eb90cf885 --- /dev/null +++ b/docs/source/docs/contributing/developer-docs/index.rst @@ -0,0 +1,6 @@ +PhotonVision Developer Documentation +==================================== + +.. toctree:: + + photonlib-backups diff --git a/docs/source/docs/contributing/developer-docs/photonlib-backups.md b/docs/source/docs/contributing/developer-docs/photonlib-backups.md new file mode 100644 index 0000000000..87e01703c9 --- /dev/null +++ b/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 +``` diff --git a/docs/source/docs/contributing/index.rst b/docs/source/docs/contributing/index.rst index 14b1dceb56..1780ba849f 100644 --- a/docs/source/docs/contributing/index.rst +++ b/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 diff --git a/docs/source/docs/contributing/photonvision-docs/index.rst b/docs/source/docs/contributing/photonvision-docs/index.rst deleted file mode 100644 index d869754ac1..0000000000 --- a/docs/source/docs/contributing/photonvision-docs/index.rst +++ /dev/null @@ -1,8 +0,0 @@ -Contributing to PhotonVision Documentation -========================================== - -.. toctree:: - - building-docs - style-guide - top-contributors diff --git a/docs/source/docs/contributing/photonvision-docs/style-guide.rst b/docs/source/docs/contributing/photonvision-docs/style-guide.rst deleted file mode 100644 index 6b130c76e8..0000000000 --- a/docs/source/docs/contributing/photonvision-docs/style-guide.rst +++ /dev/null @@ -1,3 +0,0 @@ -Style Guide -=========== -PhotonVision follows the frc-docs style guide which can be found `here `_. In order to run the linter locally (which builds on doc8 and checks for compliance with the style guide), follow the instructions `on GitHub `_. diff --git a/docs/source/docs/contributing/photonvision-docs/top-contributors.rst b/docs/source/docs/contributing/photonvision-docs/top-contributors.rst deleted file mode 100644 index bc1fe933ea..0000000000 --- a/docs/source/docs/contributing/photonvision-docs/top-contributors.rst +++ /dev/null @@ -1,5 +0,0 @@ -Top Contributors -================ - -.. ghcontributors:: PhotonVision/photonvision-docs - :limit: 10 diff --git a/docs/source/docs/contributing/photonvision/index.rst b/docs/source/docs/contributing/photonvision/index.rst deleted file mode 100644 index 93185e0641..0000000000 --- a/docs/source/docs/contributing/photonvision/index.rst +++ /dev/null @@ -1,7 +0,0 @@ -Contributing to PhotonVision -============================ - -.. toctree:: - - build-instructions - top-contributors diff --git a/docs/source/docs/contributing/photonvision/top-contributors.rst b/docs/source/docs/contributing/photonvision/top-contributors.rst deleted file mode 100644 index 9c27a60562..0000000000 --- a/docs/source/docs/contributing/photonvision/top-contributors.rst +++ /dev/null @@ -1,5 +0,0 @@ -Top Contributors -================ - -.. ghcontributors:: PhotonVision/photonvision - :limit: 10 diff --git a/docs/source/docs/installation/updating.rst b/docs/source/docs/installation/updating.rst index f5a98fbec1..dff11508c2 100644 --- a/docs/source/docs/installation/updating.rst +++ b/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 `. +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 `. .. 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. diff --git a/docs/source/docs/programming/photonlib/adding-vendordep.rst b/docs/source/docs/programming/photonlib/adding-vendordep.rst index 178ad29c53..92f34b14f0 100644 --- a/docs/source/docs/programming/photonlib/adding-vendordep.rst +++ b/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 ` 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 ` for more details on installing vendor libraries offline. Install - Python ---------------- diff --git a/photon-docs/README.md b/photon-docs/README.md new file mode 100644 index 0000000000..9b31e7a6dc --- /dev/null +++ b/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/ .