Skip to content

Commit 480579d

Browse files
MJC598MJC598
authored
[Feature] Conditional Documentation and CMake instead of Submodule for Doxygen-Is-Awesome (#123)
* Adding conditional documentation building * Updating workflow for doc deployment * Addressing PR comment
1 parent d7654eb commit 480579d

9 files changed

Lines changed: 94 additions & 50 deletions

File tree

‎.github/workflows/deploy-docs.yml‎

Lines changed: 56 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -3,45 +3,60 @@ name: Docs
33
# Controls when the action will run. Triggers the workflow on push or pull request
44
# events but only for the master branch
55
on:
6-
push:
7-
branches: ["main"]
8-
workflow_dispatch:
9-
6+
push:
7+
branches: ["main"]
8+
workflow_dispatch:
9+
1010
jobs:
11-
deploy:
12-
runs-on: ubuntu-latest
13-
steps:
14-
- name: Checkout repository
15-
uses: actions/checkout@v4
16-
with:
17-
submodules: "true"
18-
19-
- name: Install dependencies
20-
run: sudo apt-get update && sudo apt-get install -y wget graphviz rsync
21-
shell: bash
22-
23-
- name: Install Doxygen v1.9.6
24-
run: |
25-
transformed_version=$(echo "1.9.6" | tr '.' '_')
26-
wget https://github.com/doxygen/doxygen/releases/download/Release_${transformed_version}/doxygen-1.9.6.linux.bin.tar.gz
27-
tar -xzf doxygen-1.9.6.linux.bin.tar.gz
28-
sudo mv doxygen-1.9.6/bin/doxygen /usr/local/bin/doxygen
29-
shell: bash
30-
31-
- name: Generate Doxygen Documentation
32-
run: doxygen Doxyfile
33-
shell: bash
34-
35-
- name: Create .nojekyll (ensures pages with underscores work on gh pages)
36-
run: touch docs/doxygen/html/.nojekyll
37-
shell: bash
38-
39-
- name: Deploy to GitHub Pages
40-
uses: JamesIves/github-pages-deploy-action@v4
41-
with:
42-
repository-name: SyndemicsLab/respond
43-
branch: gh-pages
44-
folder: docs/doxygen/html
45-
target-folder: ./
46-
ssh-key: ${{ secrets.RESPOND_DOCS_DEPLOY_SSH_PRIVATE }}
47-
token: ${{ secrets.OAUTH_TOKEN }}
11+
deploy:
12+
runs-on: ubuntu-latest
13+
steps:
14+
- name: Checkout repository
15+
uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8
16+
with:
17+
submodules: "true"
18+
19+
- name: Install dependencies
20+
run: sudo apt-get update && sudo apt-get install -y wget graphviz rsync
21+
shell: bash
22+
23+
- name: Install Doxygen v1.9.6
24+
run: |
25+
transformed_version=$(echo "1.9.6" | tr '.' '_')
26+
wget https://github.com/doxygen/doxygen/releases/download/Release_${transformed_version}/doxygen-1.9.6.linux.bin.tar.gz
27+
tar -xzf doxygen-1.9.6.linux.bin.tar.gz
28+
sudo mv doxygen-1.9.6/bin/doxygen /usr/local/bin/doxygen
29+
shell: bash
30+
31+
- name: Install Eigen3
32+
uses: kupns-aka-kupa/setup-eigen3@master
33+
id: install-eigen3
34+
with:
35+
version: 3.4.0
36+
env:
37+
CMAKE_GENERATOR: Ninja
38+
39+
- name: Configure Project
40+
env:
41+
EIGEN3_INCLUDE_DIR: ${{ steps.install-eigen3.outputs.EIGEN3_INCLUDE_DIR }}
42+
EIGEN3_DIR: ${{ steps.install-eigen3.outputs.EIGEN3_DIR}}
43+
run: >
44+
cmake --config --preset release-linux-shared-config
45+
46+
- name: Generate Doxygen Documentation
47+
run: doxygen Doxyfile
48+
shell: bash
49+
50+
- name: Create .nojekyll (ensures pages with underscores work on gh pages)
51+
run: touch docs/doxygen/html/.nojekyll
52+
shell: bash
53+
54+
- name: Deploy to GitHub Pages
55+
uses: JamesIves/github-pages-deploy-action@v4
56+
with:
57+
repository-name: SyndemicsLab/respond
58+
branch: gh-pages
59+
folder: docs/doxygen/html
60+
target-folder: ./
61+
ssh-key: ${{ secrets.RESPOND_DOCS_DEPLOY_SSH_PRIVATE }}
62+
token: ${{ secrets.OAUTH_TOKEN }}

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
# Doxyfile generated by CMake Configuration
2+
# Because we include doxygen-is-awesome we need to render the Doxygen file each time CMake is run. Thus, the base Doxyfile must become a generated file during CMake configuration.
3+
# To modify the Doxyfile, edit docs/Doxyfile.in and re-run CMake. It will build the new Doxyfile at the root of the build tree.
4+
Doxyfile
5+
16
.metadata
27
bin/
38
tmp/

‎.gitmodules‎

Lines changed: 0 additions & 3 deletions
This file was deleted.

‎CMakePresets.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,7 @@
5656
"CMAKE_BUILD_TYPE": "Release",
5757
"RESPOND_BUILD_TESTS": "OFF",
5858
"RESPOND_INSTALL": "ON",
59+
"RESPOND_BUILD_DOCS": "ON",
5960
"RESPOND_CALCULATE_COVERAGE": "OFF"
6061
}
6162
},

Doxyfile renamed to Doxyfile.in

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1377,9 +1377,9 @@ HTML_STYLESHEET =
13771377
# documentation.
13781378
# This tag requires that the tag GENERATE_HTML is set to YES.
13791379

1380-
HTML_EXTRA_STYLESHEET = docs/doxygen-awesome-css/doxygen-awesome.css \
1381-
docs/doxygen-awesome-css/doxygen-awesome-sidebar-only.css \
1382-
docs/doxygen-awesome-css/doxygen-awesome-sidebar-only-darkmode-toggle.css \
1380+
HTML_EXTRA_STYLESHEET = @AWESOME_CSS_DIR@/doxygen-awesome.css \
1381+
@AWESOME_CSS_DIR@/doxygen-awesome-sidebar-only.css \
1382+
@AWESOME_CSS_DIR@/doxygen-awesome-sidebar-only-darkmode-toggle.css \
13831383
docs/src/custom.css
13841384

13851385
# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
@@ -1390,8 +1390,8 @@ HTML_EXTRA_STYLESHEET = docs/doxygen-awesome-css/doxygen-awesome.css \
13901390
# files will be copied as-is; there are no commands or markers available.
13911391
# This tag requires that the tag GENERATE_HTML is set to YES.
13921392

1393-
HTML_EXTRA_FILES = docs/doxygen-awesome-css/doxygen-awesome-darkmode-toggle.js \
1394-
docs/doxygen-awesome-css/doxygen-awesome-fragment-copy-button.js \
1393+
HTML_EXTRA_FILES = @AWESOME_CSS_DIR@/doxygen-awesome-darkmode-toggle.js \
1394+
@AWESOME_CSS_DIR@/doxygen-awesome-fragment-copy-button.js \
13951395
docs/images/png/favicon.png
13961396

13971397
# The HTML_COLORSTYLE tag can be used to specify if the generated HTML output

‎cmake/BuildBinaries.cmake‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,4 +11,9 @@ endif()
1111
if(RESPOND_BUILD_BENCH OR RESPOND_BUILD_ALL)
1212
message(STATUS "Generating benchmarks")
1313
add_subdirectory(extras/benchmarking)
14+
endif()
15+
16+
if(RESPOND_BUILD_DOCS OR RESPOND_BUILD_ALL)
17+
message(STATUS "Generating documentation")
18+
include(${PRIVATE_MODULE_PATH}/LoadDoxygenIsAwesome.cmake)
1419
endif()

‎cmake/LoadDoxygenIsAwesome.cmake‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
2+
message(CHECK_START "Fetching DoxygenIsAwesome...")
3+
list(APPEND CMAKE_MESSAGE_INDENT " ")
4+
include(FetchContent)
5+
6+
FetchContent_Declare(
7+
doxygen-awesome-css
8+
URL https://github.com/jothepro/doxygen-awesome-css/archive/refs/heads/main.zip
9+
)
10+
FetchContent_MakeAvailable(doxygen-awesome-css)
11+
12+
# Save the location the files were cloned into
13+
# This allows us to get the path to doxygen-awesome.css
14+
FetchContent_GetProperties(doxygen-awesome-css SOURCE_DIR AWESOME_CSS_DIR)
15+
16+
# Generate the Doxyfile
17+
set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
18+
set(DOXYFILE_OUT ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile)
19+
configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)

‎cmake/options.cmake‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,9 @@ option(RESPOND_BUILD_PIC "Build position independent code (-fPIC)" OFF)
66
# build shared libraries
77
option(BUILD_SHARED_LIBS "Build shared libraries instead of static libraries" ON)
88

9+
# build documentation
10+
option(RESPOND_BUILD_DOCS "Build Documentation" ON)
11+
912
# testing options
1013
option(RESPOND_BUILD_TESTS "Build tests" OFF)
1114

‎docs/doxygen-awesome-css‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

0 commit comments

Comments
 (0)