From 9ad9b8288a98db7ed1a5174ff28209407aa34006 Mon Sep 17 00:00:00 2001 From: Matt Date: Thu, 4 Jul 2024 17:15:51 -0400 Subject: [PATCH] Update docs on docs about docs (#1360) --- .readthedocs.yaml | 2 +- docs/.readthedocs.yaml | 15 --------------- .../photonvision-docs/building-docs.rst | 17 +++++++++-------- 3 files changed, 10 insertions(+), 24 deletions(-) delete mode 100644 docs/.readthedocs.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 773d340b3e..8b3ef1aca6 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -18,7 +18,7 @@ build: # If there are no changes (git diff exits with 0) we force the command to return with 183. # This is a special exit code on Read the Docs that will cancel the build immediately. - | - if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/master -- docs/ docs/.readthedocs.yaml; + if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/master -- docs/ .readthedocs.yaml; then exit 183; fi diff --git a/docs/.readthedocs.yaml b/docs/.readthedocs.yaml deleted file mode 100644 index 3b80b77b96..0000000000 --- a/docs/.readthedocs.yaml +++ /dev/null @@ -1,15 +0,0 @@ -version: 2 - -sphinx: - builder: html - configuration: source/conf.py - fail_on_warning: true - -build: - os: ubuntu-22.04 - tools: - python: "3.11" - -python: - install: - - requirements: requirements.txt diff --git a/docs/source/docs/contributing/photonvision-docs/building-docs.rst b/docs/source/docs/contributing/photonvision-docs/building-docs.rst index 93f63d6cd0..3133721245 100644 --- a/docs/source/docs/contributing/photonvision-docs/building-docs.rst +++ b/docs/source/docs/contributing/photonvision-docs/building-docs.rst @@ -4,29 +4,30 @@ To build the PhotonVision documentation, you will require `Git `_. To clone this fork, run the following command in a terminal window: -``git clone https://github.com/[your username]/photonvision-docs`` +Documentation lives within the main PhotonVision repository within the `docs` sub-folder. If you are planning on contributing, it is recommended to create a fork of the `PhotonVision repository `_. To clone this fork, run the following command in a terminal window: + +``git clone https://github.com/[your username]/photonvision`` Installing Python Dependencies ------------------------------ -You must install a set of Python dependencies in order to build the documentation. To do so, you can run the following command in the root project directory: +You must install a set of Python dependencies in order to build the documentation. To do so, you can run the following command in the docs sub-folder: -``python -m pip install -r requirements.txt`` +``~/photonvision/docs$ python -m pip install -r requirements.txt`` Building the Documentation -------------------------- -In order to build the documentation, you can run the following command in the root project directory: +In order to build the documentation, you can run the following command in the docs sub-folder: -``make html`` +``~/photonvision/docs$ make html`` .. note:: You may have to run ``./make html`` on Windows. Opening the Documentation ------------------------- -The built documentation is located at ``build/html/index.html``. +The built documentation is located at ``docs/build/html/index.html`` relative to the root project directory. 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`` +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.