Move docs in-source (#1357)

Author: mcm001

.github/workflows/build.yml

@@ -1,12 +1,21 @@
 name: Build
 
 on:
+  # Run on pushes to master and pushed tags, and on pull requests against master, but ignore the docs folder
   push:
     branches: [ master ]
     tags:
       - 'v*'
+    paths:
+      - '**'
+      - '!docs/**'
+      - '.github/**'
   pull_request:
     branches: [ master ]
+    paths:
+      - '**'
+      - '!docs/**'
+      - '.github/**'
 
 jobs:
   build-client:
@@ -101,24 +110,23 @@ jobs:
     runs-on: ubuntu-22.04
     steps:
       - uses: actions/checkout@v4
-        with:
-          repository: 'PhotonVision/photonvision-docs.git'
-          ref: master
       - uses: actions/setup-python@v5
         with:
-          python-version: '3.9'
+          python-version: '3.11'
       - name: Install dependencies
+        working-directory: docs
         run: |
           python -m pip install --upgrade pip
           pip install sphinx sphinx_rtd_theme sphinx-tabs sphinxext-opengraph doc8
           pip install -r requirements.txt
       - name: Build the docs
+        working-directory: docs
         run: |
           make html
       - uses: actions/upload-artifact@v4
         with:
           name: built-docs
-          path: build/html
+          path: docs/build/html
   build-photonlib-host:
     env:
       MACOSX_DEPLOYMENT_TARGET: 13

.github/workflows/lint-format.yml

@@ -1,12 +1,21 @@
 name: Lint and Format
 
 on:
+  # Run on pushes to master and pushed tags, and on pull requests against master, but ignore the docs folder
   push:
     branches: [ master ]
     tags:
       - 'v*'
+    paths:
+      - '**'
+      - '!docs/**'
+      - '.github/**'
   pull_request:
     branches: [ master ]
+    paths:
+      - '**'
+      - '!docs/**'
+      - '.github/**'
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
@@ -26,9 +35,9 @@ jobs:
       - name: Set up Python 3.8
         uses: actions/setup-python@v4
         with:
-          python-version: 3.8
+          python-version: 3.11
       - name: Install wpiformat
-        run: pip3 install wpiformat
+        run: pip3 install wpiformat==2024.37
       - name: Run
         run: wpiformat
       - name: Check output

.github/workflows/documentation.yml renamed to .github/workflows/photon-code-docs.yml

@@ -1,12 +1,21 @@
-name: Documentation
+name: Photon Code Documentation
 
 on:
+  # Run on pushes to master and pushed tags, and on pull requests against master, but ignore the docs folder
   push:
-    # For now, run on all commits to master
     branches: [ master ]
-    # and also all tags starting with v
     tags:
       - 'v*'
+    paths:
+      - '**'
+      - '!docs/**'
+      - '.github/**'
+  pull_request:
+    branches: [ master ]
+    paths:
+      - '**'
+      - '!docs/**'
+      - '.github/**'
 
 # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
@@ -58,12 +67,12 @@ jobs:
     - name: Build javadocs/doxygen
       run: |
         chmod +x gradlew
-        ./gradlew docs:generateJavaDocs docs:doxygen
+        ./gradlew photon-docs:generateJavaDocs photon-docs:doxygen
 
     - uses: actions/upload-artifact@v4
       with:
         name: built-docs
-        path: docs/build/docs
+        path: photon-docs/build/docs
 
   release:
     needs: [build-client, run_docs]
@@ -76,6 +85,7 @@ jobs:
 
       - run: find .
       - name: copy file via ssh password
+        if: github.ref == 'refs/heads/master'
         uses: appleboy/[email protected]
         with:
           host: ${{ secrets.WEBMASTER_SSH_HOST }}

.github/workflows/photonvision-docs.yml

@@ -0,0 +1,46 @@
+name: PhotonVision Sphinx Documentation Checks
+
+on:
+  push:
+    branches: [ master ]
+    paths:
+      - 'docs/**'
+      - '.github/**'
+  pull_request:
+    branches: [ master ]
+    paths:
+      - 'docs/**'
+      - '.github/**'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - uses: actions/setup-python@v4
+      with:
+        python-version: '3.11'
+
+    - name: Install and upgrade pip
+      run: python -m pip install --upgrade pip
+
+    - name: Install Python dependencies
+      working-directory: docs
+      run: |
+        pip install sphinx sphinx_rtd_theme sphinx-tabs sphinxext-opengraph doc8
+        pip install -r requirements.txt
+
+    - name: Check links
+      working-directory: docs
+      run: make linkcheck
+      continue-on-error: true
+
+    - name: Check lint
+      working-directory: docs
+      run: make lint
+
+    - name: Compile HTML
+      working-directory: docs
+      run: make html

.github/workflows/python.yml

@@ -8,8 +8,16 @@ on:
     branches: [ master ]
     tags:
       - 'v*'
+    paths:
+      - '**'
+      - '!docs/**'
+      - '.github/**'
   pull_request:
     branches: [ master ]
+    paths:
+      - '**'
+      - '!docs/**'
+      - '.github/**'
 
 jobs:
   buildAndDeploy:

docs/.gitignore

@@ -0,0 +1,11 @@
+build/*
+.DS_Store
+.vscode/*
+.idea/*
+source/_build
+source/_build
+photon-docs/build
+source/docs/_build
+
+venv/*
+.venv/*

docs/.readthedocs.yml

@@ -0,0 +1,15 @@
+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

docs/.styleguide

@@ -0,0 +1,16 @@
+
+modifiableFileExclude {
+  \.jpg$
+  \.jpeg$
+  \.png$
+  \.gif$
+  \.so$
+  \.pdf$
+  \.mp4$
+  \.dll$
+  \.webp$
+  \.ico$
+  \.rknn$
+  \.svg$
+  gradlew
+}