From 231a76fe5b7509b5de767c41276a7d1f425c66c9 Mon Sep 17 00:00:00 2001 From: Kevin Ring Date: Fri, 13 Dec 2024 08:58:16 +1100 Subject: [PATCH 1/3] Production doc script improvements. - Use Doxygen 1.12. - Use ccache and the vcpkg artifacts cache to improve performance. - Run the doc deploy in both the `cesium.com` and `cesium.com-staging` branches. In the latter, deploy to `cesium-native/ref-doc-staging/` instead of the usual place. This allows us to test doc changes without affecting production. --- .github/workflows/prod.yml | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/.github/workflows/prod.yml b/.github/workflows/prod.yml index b9dd66322..c4730865b 100644 --- a/.github/workflows/prod.yml +++ b/.github/workflows/prod.yml @@ -3,6 +3,7 @@ on: push: branches: - 'cesium.com' + - 'cesium.com-staging' jobs: deploy-docs: runs-on: ubuntu-22.04 @@ -13,17 +14,38 @@ jobs: steps: - name: Install Doxygen run: | - sudo apt install -y doxygen + cd ~ + wget https://github.com/doxygen/doxygen/releases/download/Release_1_12_0/doxygen-1.12.0.linux.bin.tar.gz + tar xzf doxygen-1.12.0.linux.bin.tar.gz + export PATH=$PWD/doxygen-1.12.0/bin:$PATH + echo "PATH=$PATH" >> "$GITHUB_ENV" + doxygen --version - name: Check out repository code uses: actions/checkout@v4 with: submodules: recursive + - name: ccache + uses: hendrikmuhs/ccache-action@v1.2.9 + with: + key: ccache-ubuntu-22.04-doxygen + - name: Cache vcpkg artifacts + uses: actions/cache@v4 + with: + path: ~/.ezvcpkg + key: vcpkg-ubuntu-22.04-doxygen-${{ hashFiles('CMakeLists.txt') }} + restore-keys: | + vcpkg-ubuntu-22.04-doxygen-${{ hashFiles('CMakeLists.txt') }} + vcpkg-ubuntu-22.04-doxygen - name: Generate Documentation run: | npm install cmake -B build -S . cmake --build build --target cesium-native-docs - name: Deploy to cesium.com - if: ${{ env.AWS_ACCESS_KEY_ID != '' }} + if: ${{ github.ref_name == 'cesium.com' }} run: | aws s3 sync build/doc/html/ s3://cesium-website/cesium-native/ref-doc/ --cache-control "public, max-age=1800" --delete + - name: Deploy to cesium.com staging + if: ${{ github.ref_name == 'cesium.com-staging' }} + run: | + aws s3 sync build/doc/html/ s3://cesium-website/cesium-native/ref-doc-staging/ --cache-control "public, max-age=1800" --delete From 4ce1bcb3945f40cefc405d7f7b52d71c95649897 Mon Sep 17 00:00:00 2001 From: Kevin Ring Date: Fri, 13 Dec 2024 10:33:00 +1100 Subject: [PATCH 2/3] Mark docs pre-release in staging. --- .github/workflows/prod.yml | 6 +++++- doc/CMakeLists.txt | 4 ++++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/.github/workflows/prod.yml b/.github/workflows/prod.yml index c4730865b..fa7f4e133 100644 --- a/.github/workflows/prod.yml +++ b/.github/workflows/prod.yml @@ -36,10 +36,14 @@ jobs: restore-keys: | vcpkg-ubuntu-22.04-doxygen-${{ hashFiles('CMakeLists.txt') }} vcpkg-ubuntu-22.04-doxygen + - name: Mark documentation official + if: ${{ github.ref_name == 'cesium.com' }} + run: | + echo "EXTRA_CONFIGURE_ARGS=-DCESIUM_PRODUCTION_DOCS" >> "$GITHUB_ENV" - name: Generate Documentation run: | npm install - cmake -B build -S . + cmake -B build -S . $EXTRA_CONFIGURE_ARGS cmake --build build --target cesium-native-docs - name: Deploy to cesium.com if: ${{ github.ref_name == 'cesium.com' }} diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 1af199be3..9402a6bef 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -87,6 +87,10 @@ if(DOXYGEN_FOUND) set(DOXYGEN_EXCLUDE_PATTERNS "*/node_modules/*") set(DOXYGEN_IMAGE_PATH "./") + if(NOT CESIUM_PRODUCTION_DOCS) + set(DOXYGEN_PROJECT_BRIEF "PRE-RELEASE") + endif() + # Add support for Mermaid charts using the @mermaid command. set(DOXYGEN_HTML_EXTRA_FILES "${CMAKE_CURRENT_LIST_DIR}/assets/mermaid.min.js ${CMAKE_CURRENT_LIST_DIR}/assets/mingcute.json.js") set(DOXYGEN_ALIASES mermaid{1}="\\htmlonly
^^ \\endhtmlonly \\htmlinclude \\\"\\1.mmd\\\" \\htmlonly ^^
\\endhtmlonly") From 62c4e31b15f71e5f812c536aae8649dbcf24525f Mon Sep 17 00:00:00 2001 From: Ashley Rogers Date: Wed, 18 Dec 2024 10:19:56 -0500 Subject: [PATCH 3/3] Add `noindex` tag for pre-release docs --- doc/CMakeLists.txt | 3 ++ doc/header-noindex.html | 81 +++++++++++++++++++++++++++++++++++++++++ doc/header.html | 80 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 164 insertions(+) create mode 100644 doc/header-noindex.html create mode 100644 doc/header.html diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 9402a6bef..c5ba67472 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -89,6 +89,9 @@ if(DOXYGEN_FOUND) if(NOT CESIUM_PRODUCTION_DOCS) set(DOXYGEN_PROJECT_BRIEF "PRE-RELEASE") + set(DOXYGEN_HTML_HEADER "${CMAKE_CURRENT_LIST_DIR}/header-noindex.html") + else() + set(DOXYGEN_HTML_HEADER "${CMAKE_CURRENT_LIST_DIR}/header.html") endif() # Add support for Mermaid charts using the @mermaid command. diff --git a/doc/header-noindex.html b/doc/header-noindex.html new file mode 100644 index 000000000..a8262c005 --- /dev/null +++ b/doc/header-noindex.html @@ -0,0 +1,81 @@ + + + + + + + + + +$projectname: $title +$title + + + + + + + + + + + + + + +$treeview +$search +$mathjax +$darkmode + +$extrastylesheet + + + + +
+ + + +
+ + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
$projectname $projectnumber +
+
$projectbrief
+ 		+
$projectbrief
+ 		$searchbox
$searchbox
+
+ + diff --git a/doc/header.html b/doc/header.html new file mode 100644 index 000000000..9b8c11847 --- /dev/null +++ b/doc/header.html @@ -0,0 +1,80 @@ + + + + + + + + +$projectname: $title +$title + + + + + + + + + + + + + + +$treeview +$search +$mathjax +$darkmode + +$extrastylesheet + + + + +
+ + + +
+ + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
$projectname $projectnumber +
+
$projectbrief
+ 		+
$projectbrief
+ 		$searchbox
$searchbox
+
+ +