From fc09efbfdb2580aef0180b9415677b43125eafc8 Mon Sep 17 00:00:00 2001 From: Matt Date: Sun, 4 Aug 2024 09:35:30 -0700 Subject: [PATCH 1/4] Add rsync docs --- .github/workflows/build.yml | 2 +- docs/.gitignore | 2 -- docs/requirements.txt | 2 ++ docs/source/conf.py | 2 ++ .../photonvision-docs/building-docs.rst | 8 +++----- docs/source/docs/developer-docs/index.rst | 6 ++++++ .../docs/developer-docs/photonlib-backups.md | 16 ++++++++++++++++ .../programming/photonlib/adding-vendordep.rst | 2 +- docs/source/index.rst | 7 +++++++ photon-docs/README.md | 3 +++ 10 files changed, 41 insertions(+), 9 deletions(-) create mode 100644 docs/source/docs/developer-docs/index.rst create mode 100644 docs/source/docs/developer-docs/photonlib-backups.md create mode 100644 photon-docs/README.md 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..fd4b536658 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,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") diff --git a/docs/source/docs/contributing/photonvision-docs/building-docs.rst b/docs/source/docs/contributing/photonvision-docs/building-docs.rst index 3133721245..49c463e3bb 100644 --- a/docs/source/docs/contributing/photonvision-docs/building-docs.rst +++ b/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 ---------------------------- diff --git a/docs/source/docs/developer-docs/index.rst b/docs/source/docs/developer-docs/index.rst new file mode 100644 index 0000000000..3eb90cf885 --- /dev/null +++ b/docs/source/docs/developer-docs/index.rst @@ -0,0 +1,6 @@ +PhotonVision Developer Documentation +==================================== + +.. toctree:: + + photonlib-backups diff --git a/docs/source/docs/developer-docs/photonlib-backups.md b/docs/source/docs/developer-docs/photonlib-backups.md new file mode 100644 index 0000000000..165c3049ef --- /dev/null +++ b/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 +``` diff --git a/docs/source/docs/programming/photonlib/adding-vendordep.rst b/docs/source/docs/programming/photonlib/adding-vendordep.rst index 178ad29c53..f085e9d8be 100644 --- a/docs/source/docs/programming/photonlib/adding-vendordep.rst +++ b/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`. diff --git a/docs/source/index.rst b/docs/source/index.rst index 62a87b4c05..3d5fa5f25e 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -110,3 +110,10 @@ PhotonVision is licensed under the `GNU GPL v3 Date: Mon, 5 Aug 2024 21:17:24 -0700 Subject: [PATCH 2/4] Move per suggestions --- .../{photonvision => }/assets/git-download.png | Bin .../{photonvision-docs => }/building-docs.rst | 4 ++++ .../build-instructions.rst => building-photon.rst} | 0 .../{ => contributing}/developer-docs/index.rst | 0 .../developer-docs/photonlib-backups.md | 2 +- docs/source/docs/contributing/index.rst | 5 +++-- .../docs/contributing/photonvision-docs/index.rst | 8 -------- .../contributing/photonvision-docs/style-guide.rst | 3 --- .../photonvision-docs/top-contributors.rst | 5 ----- .../source/docs/contributing/photonvision/index.rst | 7 ------- .../contributing/photonvision/top-contributors.rst | 5 ----- .../docs/programming/photonlib/adding-vendordep.rst | 5 ++++- docs/source/index.rst | 7 ------- 13 files changed, 12 insertions(+), 39 deletions(-) rename docs/source/docs/contributing/{photonvision => }/assets/git-download.png (100%) rename docs/source/docs/contributing/{photonvision-docs => }/building-docs.rst (85%) rename docs/source/docs/contributing/{photonvision/build-instructions.rst => building-photon.rst} (100%) rename docs/source/docs/{ => contributing}/developer-docs/index.rst (100%) rename docs/source/docs/{ => contributing}/developer-docs/photonlib-backups.md (97%) delete mode 100644 docs/source/docs/contributing/photonvision-docs/index.rst delete mode 100644 docs/source/docs/contributing/photonvision-docs/style-guide.rst delete mode 100644 docs/source/docs/contributing/photonvision-docs/top-contributors.rst delete mode 100644 docs/source/docs/contributing/photonvision/index.rst delete mode 100644 docs/source/docs/contributing/photonvision/top-contributors.rst 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 85% rename from docs/source/docs/contributing/photonvision-docs/building-docs.rst rename to docs/source/docs/contributing/building-docs.rst index 49c463e3bb..d3da03b0a4 100644 --- a/docs/source/docs/contributing/photonvision-docs/building-docs.rst +++ b/docs/source/docs/contributing/building-docs.rst @@ -29,3 +29,7 @@ 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/developer-docs/index.rst b/docs/source/docs/contributing/developer-docs/index.rst similarity index 100% rename from docs/source/docs/developer-docs/index.rst rename to docs/source/docs/contributing/developer-docs/index.rst diff --git a/docs/source/docs/developer-docs/photonlib-backups.md b/docs/source/docs/contributing/developer-docs/photonlib-backups.md similarity index 97% rename from docs/source/docs/developer-docs/photonlib-backups.md rename to docs/source/docs/contributing/developer-docs/photonlib-backups.md index 165c3049ef..6a08a84de4 100644 --- a/docs/source/docs/developer-docs/photonlib-backups.md +++ b/docs/source/docs/contributing/developer-docs/photonlib-backups.md @@ -12,5 +12,5 @@ Artifacts from our Maven server can also be backed up locally to a folder called ``` 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 +/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/programming/photonlib/adding-vendordep.rst b/docs/source/docs/programming/photonlib/adding-vendordep.rst index f085e9d8be..92f34b14f0 100644 --- a/docs/source/docs/programming/photonlib/adding-vendordep.rst +++ b/docs/source/docs/programming/photonlib/adding-vendordep.rst @@ -19,10 +19,13 @@ 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++ -------------------------- -Download the latest photonlib release from our GitHub releases page, and extract the contents to `$HOME/wpilib/YEAR`. +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 ---------------- Add photonlibpy to `pyproject.toml`. diff --git a/docs/source/index.rst b/docs/source/index.rst index 3d5fa5f25e..62a87b4c05 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -110,10 +110,3 @@ PhotonVision is licensed under the `GNU GPL v3 Date: Mon, 5 Aug 2024 21:21:20 -0700 Subject: [PATCH 3/4] oops --- docs/source/docs/installation/updating.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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. From 48dc6be2b799084ad3816d270ef8b6ec37fc3678 Mon Sep 17 00:00:00 2001 From: Matt Date: Mon, 5 Aug 2024 21:22:07 -0700 Subject: [PATCH 4/4] run lint --- docs/source/conf.py | 3 ++- .../docs/contributing/developer-docs/photonlib-backups.md | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index fd4b536658..48c878bdf6 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -72,7 +72,8 @@ # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ["_static"] -source_suffix = ['.rst', '.md'] +source_suffix = [".rst", ".md"] + def setup(app): app.add_css_file("css/pv-icons.css") diff --git a/docs/source/docs/contributing/developer-docs/photonlib-backups.md b/docs/source/docs/contributing/developer-docs/photonlib-backups.md index 6a08a84de4..87e01703c9 100644 --- a/docs/source/docs/contributing/developer-docs/photonlib-backups.md +++ b/docs/source/docs/contributing/developer-docs/photonlib-backups.md @@ -2,7 +2,7 @@ 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).