Add automated doc builds via GitHub pages

[mborland]

This adds a workflow for building and deploying the documentation. Updates the README to point to edgcpp.org/compiler/ since GitHub Pages follows the names of the repos, but if need be we can stick a redirect in the main website repository that redirects edgcpp.org/doc/ to edgcpp.org/compiler.

[DarkArc]

I was thinking of something more like:

diff --git a/.github/workflows/build_and_deploy.yml b/.github/workflows/build_and_deploy.yml
index cb89899..53821b9 100644
--- a/.github/workflows/build_and_deploy.yml
+++ b/.github/workflows/build_and_deploy.yml
@@ -15,6 +15,16 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
+      - name: Build compiler documentation
+        run: |
+          git clone --depth 1 --branch 7.0 https://github.com/edgcpp/compiler.git /tmp/compiler
+          docker run --rm \
+            -v /tmp/compiler:/work \
+            -w /work/doc \
+            edgcpp/sphinx-env:latest \
+            make dirhtml
+          mkdir -p doc
+          cp -a /tmp/compiler/doc/build/dirhtml/. doc/
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: '4.0'
@@ -29,6 +39,16 @@ jobs:
       contents: write
     steps:
       - uses: actions/checkout@v5
+      - name: Build compiler documentation
+        run: |
+          git clone --depth 1 --branch 7.0 https://github.com/edgcpp/compiler.git /tmp/compiler
+          docker run --rm \
+            -v /tmp/compiler:/work \
+            -w /work/doc \
+            edgcpp/sphinx-env:latest \
+            make dirhtml
+          mkdir -p doc
+          cp -a /tmp/compiler/doc/build/dirhtml/. doc/
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: '4.0'

in the https://github.com/edgcpp/edgcpp.github.io repo.

[mborland]

I was thinking of something more like:

diff --git a/.github/workflows/build_and_deploy.yml b/.github/workflows/build_and_deploy.yml
index cb89899..53821b9 100644
--- a/.github/workflows/build_and_deploy.yml
+++ b/.github/workflows/build_and_deploy.yml
@@ -15,6 +15,16 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
+      - name: Build compiler documentation
+        run: |
+          git clone --depth 1 --branch 7.0 https://github.com/edgcpp/compiler.git /tmp/compiler
+          docker run --rm \
+            -v /tmp/compiler:/work \
+            -w /work/doc \
+            edgcpp/sphinx-env:latest \
+            make dirhtml
+          mkdir -p doc
+          cp -a /tmp/compiler/doc/build/dirhtml/. doc/
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: '4.0'
@@ -29,6 +39,16 @@ jobs:
       contents: write
     steps:
       - uses: actions/checkout@v5
+      - name: Build compiler documentation
+        run: |
+          git clone --depth 1 --branch 7.0 https://github.com/edgcpp/compiler.git /tmp/compiler
+          docker run --rm \
+            -v /tmp/compiler:/work \
+            -w /work/doc \
+            edgcpp/sphinx-env:latest \
+            make dirhtml
+          mkdir -p doc
+          cp -a /tmp/compiler/doc/build/dirhtml/. doc/
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: '4.0'

in the https://github.com/edgcpp/edgcpp.github.io repo.

That would be fine too; I see there's a 7.0 tag instead of branch so that works. Does your development model need an in-progress docs vs release docs like Boost does?

[DarkArc]

I think it would be good to have release vs in development docs for sure. My hope was to at least have release docs present under /doc and then perhaps have a /dev/doc, /nightly/doc, or something of that ilk.

[mborland]

The 7.0 tagged website is available here https://edgcpp.org/doc/. It is built out of the main website repo as suggested.

[mborland]

Ok /doc/ now tracks the specified tagged release and this workflow now triggers a build and deployment at /dev/doc so that it can track the current main branch. If either @DarkArc or @sdarwin turned on pages for this repo can you please turn it off? That way there's no possible issue with the repo trying to push to edgcpp.org/compiler in the future. I also generated a fine-grain PAT for this so I set a reminder for myself to update that token when it expires in 365 days.

[DarkArc]

GitHub pages was not enabled; looks like the cleanup here is nice. I want to check with some other folks on the workflow in the morning to make sure this agrees with the desired documentation behavior. Thanks!

[mborland]

GitHub pages was not enabled; looks like the cleanup here is nice. I want to check with some other folks on the workflow in the morning to make sure this agrees with the desired documentation behavior. Thanks!

Sounds good. If anything needs to change let me know.

[DarkArc]

After discussion I think I'm okay with merging this as-is, but some additional thoughts with fresh eyes this morning.

[mborland]

@DarkArc I think these latest two commits hit the review comments you were looking for. Once the docker.io/edgcpp/sphinx-env:latest is updated the changes to documentation.yml would be minimal. Your choice on whether you'd like to merge now or wait for the docker container to be updated on docker.io.

Attached is the required patch file:
documentation_yml.patch

[wchilders-nvidia]

Merged; thanks!