From 2cde701cff301dd25ae5889378f2110ded87d41f Mon Sep 17 00:00:00 2001 From: Sam Freund Date: Sat, 1 Nov 2025 22:38:51 -0500 Subject: [PATCH] Add documentation for linting (#2166) ## Description This adds documentation for how to lint PhotonVision, as it is not available elsewhere and people have historically needed to figure it out for themselves. It also adds an alias for linting PV. ## Meta Merge checklist: - [x] Pull Request title is [short, imperative summary](https://cbea.ms/git-commit/) of proposed changes - [x] The description documents the _what_ and _why_ - [ ] If this PR changes behavior or adds a feature, user documentation is updated - [ ] If this PR touches photon-serde, all messages have been regenerated and hashes have not changed unexpectedly - [ ] If this PR touches configuration, this is backwards compatible with settings back to v2025.3.2 - [ ] If this PR touches pipeline settings or anything related to data exchange, the frontend typing is updated - [ ] If this PR addresses a bug, a regression test for it is added --- .github/pull_request_template.md | 1 + docs/source/docs/contributing/index.md | 1 + docs/source/docs/contributing/linting.md | 43 ++++++++++++++++++++++++ 3 files changed, 45 insertions(+) create mode 100644 docs/source/docs/contributing/linting.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 704a41b1a..0d5211e4a 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -11,6 +11,7 @@ Merge checklist: - [ ] Pull Request title is [short, imperative summary](https://cbea.ms/git-commit/) of proposed changes - [ ] The description documents the _what_ and _why_ +- [ ] This PR has been [linted](https://docs.photonvision.org/en/latest/docs/contributing/linting.html). - [ ] If this PR changes behavior or adds a feature, user documentation is updated - [ ] If this PR touches photon-serde, all messages have been regenerated and hashes have not changed unexpectedly - [ ] If this PR touches configuration, this is backwards compatible with settings back to v2025.3.2 diff --git a/docs/source/docs/contributing/index.md b/docs/source/docs/contributing/index.md index 4de6c437a..80b8487ef 100644 --- a/docs/source/docs/contributing/index.md +++ b/docs/source/docs/contributing/index.md @@ -3,6 +3,7 @@ ```{toctree} building-photon building-docs +linting developer-docs/index design-descriptions/index ``` diff --git a/docs/source/docs/contributing/linting.md b/docs/source/docs/contributing/linting.md new file mode 100644 index 000000000..690113c68 --- /dev/null +++ b/docs/source/docs/contributing/linting.md @@ -0,0 +1,43 @@ +# Linting the PhotonVision Codebase + +## Versions + +:::{note} +If you work on other projects that use different versions of the same linters as PhotonVision, you may find it beneficial to use a [venv](https://docs.python.org/3/library/venv.html) instead of installing the linters globally. This will allow you to have different versions of the same linter installed for different projects. +::: + +The correct versions for each linter can be found under the linting workflow located [here](https://github.com/PhotonVision/photonvision/tree/main/.github/workflows). For *doc8*, the version can be found in `docs/requirements.txt`. If you've linted, and are still unable to pass CI, please check the versions of your linters. + +## Frontend + +### Linting the frontend + +In order to lint the frontend, run `pnpm -C photon-client lint && pnpm -C photon-client format`. This should be done from the base level of the repo. + +## Backend + +### wpiformat installation + +To lint the backend, PhotonVision uses *wpiformat* and *spotless*. Spotless is included with gradle, which means installation is not needed. To install wpiformat, run `pipx install wpiformat`. To install a specific version, run `pipx install wpiformat==`. + +### Linting the backend + +To lint, run `./gradlew spotlessApply` and `wpiformat`. + +## Documentation + +### doc8 installation + +To install *doc8*, the python tool we use to lint our documentation, run `pipx install doc8`. To install a specific version, run `pipx install doc8==`. + +### Linting the documentation + +To lint the documentation, run `doc8 docs` from the root level of the docs. + +## Alias + +The following [alias](https://www.computerworld.com/article/1373210/how-to-use-aliases-in-linux-shell-commands.html) can be added to your shell config, which will allow you to lint the entirety of the PhotonVision project by running `pvLint`. The alias will work on Linux, macOS, Git Bash on Windows, and WSL. + +```sh +alias pvLint='wpiformat -v && ./gradlew spotlessApply && pnpm -C photon-client lint && pnpm -C photon-client format && doc8 docs' +```