Update to sphinx documentation (#3078)

This updates our website to use sphinx for its documentation site. This
includes some new content around the SQL API, as well as our API
Javadoc, which we will be publishing ourselves for the first time in a
while. Publishing happens at the end of the release process (which I've
been able to test by first applying these changes to a test repo of
mine).

---------

Co-authored-by: FDB Relational Layer Authors <[email protected]>

Author: alecgrieser

.github/workflows/mixed_mode_test.yml

@@ -40,7 +40,7 @@ jobs:
       - name: Checkout Main
         run: git checkout main
       - name: Update release notes
-        run: python build/publish-mixed-mode-results.py ${{ inputs.tag }} --release-notes docs/ReleaseNotes.md --commit --run-link ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: python build/publish-mixed-mode-results.py ${{ inputs.tag }} --release-notes docs/sphinx/source/ReleaseNotes.md --commit --run-link ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
       - name: Push release notes update
         run: git push
 

.github/workflows/release.yml

@@ -10,14 +10,14 @@ jobs:
       checks: write
       contents: write
       packages: write
-      pages: write
       pull-requests: write
     steps:
       - name: Checkout sources
         uses: actions/[email protected]
         with:
           ssh-key: ${{ secrets.DEPLOY_KEY }}
       - name: Setup Base Environment
+        id: setup-base
         uses: ./actions/setup-base-env
       - name: Setup FDB
         uses: ./actions/setup-fdb
@@ -44,4 +44,31 @@ jobs:
           MAVEN_USER: ${{ secrets.MAVEN_USER }}
           MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
 
-    # TODO: Publish documentation updates
+      # Build documentation.
+      - name: Cache Python Environment
+        uses: actions/cache@v4
+        with:
+          path: docs/sphinx/.venv
+          key: ${{ runner.os }}-sphinx-python-${{ steps.setup-base.outputs.python-version }}-${{ hashFiles('docs/sphinx/requirements.txt') }}
+      - name: Build Documentation Site
+        uses: ./actions/run-gradle
+        with:
+          gradle_command: documentationSite -PreleaseBuild=true
+      - name: Upload Documentation
+        id: doc_upload
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/sphinx/.out/html/
+
+  deploy_docs:
+    runs-on: ubuntu-latest
+    needs: gradle
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.doc_upload.outputs.page_url }}
+    steps:
+      - name: Deploy Documentation
+        uses: actions/deploy-pages@v4

.gitignore

@@ -44,6 +44,11 @@ atlassian-ide-plugin.xml
 .idea/scala_settings.xml
 .idea/shelf
 
+# Built during documentation
+/docs/sphinx/.venv
+/docs/sphinx/source/api/**/index.md
+*.diagram.svg
+
 # VSCode specific files/directories
 .vscode
 **/bin

CONTRIBUTING.md

@@ -83,7 +83,7 @@ it is addressing and, upon merging of the PR into the main code line, will
 automatically mark the issue as resolved.
 
 If your pull request results in a user-visible change to the Record Layer, you should
-also update the [release notes](docs/ReleaseNotes.md). For most changes, it
+also update the [release notes](docs/sphinx/source/ReleaseNotes.md). For most changes, it
 is sufficient to fill in one of the bullets in the "next release" section of that
 document. You should include a short description of the change as well as filling in
 the issue number. The "next release" section is commented out, so the change won't

actions/release-build-publish/action.yml

@@ -51,8 +51,12 @@ runs:
       id: push_updates
       shell: bash
       run: git push origin
+      # Continue the build (including downstream steps). If the push fails, we'll create a PR
+      continue-on-error: true
     - name: Create Merge PR if conflict
-      if: failure() && steps.push_updates.conclusion == 'failure'
+      # Only create the PR if we've otherwise been successful, but the push failed. Note that
+      # we're checking the .outcome of the push step, which is applied before continue-on-error.
+      if: success() && steps.push_updates.outcome == 'failure'
       uses: peter-evans/create-pull-request@bb88e27d3f9cc69c8bc689eba126096c6fe3dded
       id: pr_on_conflict
       with:
@@ -62,3 +66,8 @@ runs:
         sign-commits: true
         body: |
           Updates from release for version ${{ steps.get_version.outputs.version }}. Conflicts during the build prevented automatic updating. Please resolve conflicts by checking out the current branch, merging, and then deleting this branch.
+
+    # Creating the PR can change the current branch. Explicitly check out the tag here for downstream builds
+    - name: Revert to tag
+      shell: bash
+      run: git checkout "${{ steps.get_version.outputs.version }}"

actions/setup-base-env/action.yml

@@ -1,5 +1,9 @@
 name: Setup Base Environment
 
+outputs:
+  python-version:
+    value: ${{ steps.setup-python.outputs.python-version }}
+
 runs:
   using: "composite"
   steps:
@@ -11,6 +15,7 @@ runs:
     - name: Setup Gradle
       uses: gradle/actions/setup-gradle@0bdd871935719febd78681f197cd39af5b6e16a6
     - name: Setup Python
+      id: setup-python
       uses: actions/setup-python@v5
       with:
         python-version: '3.13'

build.gradle

@@ -240,8 +240,8 @@ subprojects {
                     linksOffline "https://developers.google.com/protocol-buffers/docs/reference/java/", "${packageListDir}/protobuf/"
 
                     // This is for dependent sub-projects so that their links to things in the Record Layer work
-                    linksOffline "https://static.javadoc.io/org.foundationdb/fdb-extensions/${project.version}/", "${packageListDir}/fdb-extensions/"
-                    linksOffline "https://static.javadoc.io/org.foundationdb/fdb-record-layer-core/${project.version}/", "${packageListDir}/fdb-record-layer-core/"
+                    linksOffline "https://foundationdb.github.io/fdb-record-layer/api/fdb-extensions/", "${packageListDir}/fdb-extensions/"
+                    linksOffline "https://foundationdb.github.io/fdb-record-layer/api/fdb-record-layer-core/", "${packageListDir}/fdb-record-layer-core/"
                 }
             }
             compileJava {
@@ -333,6 +333,8 @@ clean.doLast {
     }
 }
 
+apply from: 'gradle/sphinx.gradle'
+
 if (!JavaVersion.current().isJava8Compatible()) {
     throw new Exception("Java 8 is required to build fdb-record-layer")
 }

build/update_release_notes.bash

@@ -31,7 +31,7 @@
 script_dir="$( dirname $0 )"
 success=0
 
-release_notes_file="${script_dir}/../docs/ReleaseNotes.md"
+release_notes_file="${script_dir}/../docs/sphinx/source/ReleaseNotes.md"
 
 if [[ -n "${GIT_BRANCH:-}" ]] ; then
     branch="${GIT_BRANCH#*/}"