Skip to content

Commit 7c58ad8

Browse files
Matthew-WhitlockMatthew-Whitlock
authored
Merge pull request #74 from sandialabs/doxygen
Add documentation to GH pages
2 parents f5447ef + e0ce1f8 commit 7c58ad8

18 files changed

+1414
-50
lines changed

‎.github/scripts/build-gh-pages.sh

+54
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
#!/bin/bash
2+
3+
4+
set -e
5+
6+
echo "Installing apt packages"
7+
sudo apt-get update >/dev/null
8+
sudo apt-get install -y wget git cmake graphviz >/dev/null
9+
10+
echo "Installing Doxygen"
11+
wget https://www.doxygen.nl/files/doxygen-1.12.0.linux.bin.tar.gz >/dev/null
12+
tar -xzf doxygen-1.12.0.linux.bin.tar.gz >/dev/null
13+
export PATH="$PWD/doxygen-1.12.0/bin:$PATH"
14+
15+
#List of branches to build docs for
16+
#TODO: Remove doxygen branch once tested
17+
BRANCHES="doxygen master develop"
18+
19+
build-docs() (
20+
git checkout $1
21+
22+
#The CMake Doxygen stuff is weird, and doesn't
23+
#properly clean up and/or overwrite old outputs.
24+
#So to make sure we get the correct doc configs,
25+
#we need to delete everything
26+
#We put the docs themselves into a hidden directory
27+
#so they don't get included in this glob
28+
rm -rf ./*
29+
30+
cmake ../ -DBUILD_DOCS=ON -DDOCS_ONLY=ON \
31+
-DFENIX_DOCS_MAN=OFF -DFENIX_BRANCH=$1 \
32+
-DFENIX_DOCS_OUTPUT=$PWD/.docs
33+
make docs
34+
)
35+
36+
git clone https://www.github.com/sandialabs/Fenix.git
37+
mkdir Fenix/build
38+
cd Fenix/build
39+
40+
for branch in $BRANCHES; do
41+
echo "Building docs for $branch"
42+
43+
#TODO: Fail if any branch fails to build,
44+
# once the develop and master branches have doxygen
45+
# merged in
46+
build-docs $branch || true
47+
48+
echo
49+
echo
50+
done
51+
52+
if [ -n "$GITHUB_ENV" ]; then
53+
echo "DOCS_DIR=$PWD/.docs" >> $GITHUB_ENV
54+
fi

‎.github/workflows/docs.yml

+40
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
name: Publish GH Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- master
7+
- develop
8+
- doxygen # TODO: Remove after testing
9+
10+
#Only one of this workflow runs at a time
11+
concurrency:
12+
group: docs
13+
cancel-in-progress: true
14+
15+
jobs:
16+
build-pages:
17+
runs-on: ubuntu-latest
18+
steps:
19+
- name: Checkout
20+
uses: actions/checkout@v4
21+
22+
- name: Build pages
23+
run: /bin/bash .github/scripts/build-gh-pages.sh
24+
25+
- name: Upload documentation artifact
26+
uses: actions/upload-pages-artifact@v3
27+
with:
28+
path: ${{ env.DOCS_DIR }}
29+
30+
deploy-docs:
31+
needs: build-pages
32+
runs-on: ubuntu-latest
33+
permissions:
34+
pages: write
35+
id-token: write
36+
37+
steps:
38+
- name: Deploy documentation to GH Pages
39+
uses: actions/deploy-pages@v4
40+

‎CMakeLists.txt

+20-15
Original file line numberDiff line numberDiff line change
@@ -16,37 +16,42 @@ set(FENIX_VERSION_MAJOR 1)
1616
set(FENIX_VERSION_MINOR 0)
1717

1818
option(BUILD_EXAMPLES "Builds example programs from the examples directory" OFF)
19-
option(BUILD_TESTING "Builds tests and test modes of files" ON)
20-
19+
option(BUILD_TESTING "Builds tests and test modes of files" ON)
20+
option(BUILD_DOCS "Builds documentation if is doxygen found" ON)
21+
option(DOCS_ONLY "Only build documentation" OFF)
2122

2223
#Solves an issue with some system environments putting their MPI headers before
2324
#the headers CMake includes. Forces non-system MPI headers when incorrect headers
2425
#detected in include path.
2526
option(FENIX_SYSTEM_INC_FIX "Attempts to force overriding any system MPI headers" ON)
2627
option(FENIX_PROPAGATE_INC_FIX "Attempt overriding system MPI headers in linking projects" ON)
2728

28-
find_package(MPI REQUIRED)
2929

30-
if(${FENIX_SYSTEM_INC_FIX})
31-
include(cmake/systemMPIOverride.cmake)
32-
endif()
30+
if(NOT DOCS_ONLY)
31+
find_package(MPI REQUIRED)
3332

33+
if(${FENIX_SYSTEM_INC_FIX})
34+
include(cmake/systemMPIOverride.cmake)
35+
endif()
3436

35-
add_subdirectory(src)
37+
add_subdirectory(src)
3638

39+
include(CTest)
40+
list(APPEND MPIEXEC_PREFLAGS "--with-ft;mpi")
3741

38-
include(CTest)
39-
list(APPEND MPIEXEC_PREFLAGS "--with-ft;mpi")
42+
if(BUILD_EXAMPLES)
43+
add_subdirectory(examples)
44+
endif()
4045

41-
if(BUILD_EXAMPLES)
42-
add_subdirectory(examples)
43-
endif()
46+
if(BUILD_TESTING)
47+
add_subdirectory(test)
48+
endif()
4449

45-
46-
if(BUILD_TESTING)
47-
add_subdirectory(test)
4850
endif()
4951

52+
if(BUILD_DOCS)
53+
add_subdirectory(doc)
54+
endif()
5055

5156
configure_file(
5257
${CMAKE_CURRENT_SOURCE_DIR}/include/fenix-config.h.in

‎doc/CMakeLists.txt

+39
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
find_package(Doxygen)
2+
3+
set(FENIX_DOCS_OUTPUT ${CMAKE_CURRENT_BINARY_DIR} CACHE PATH "Documentation output directory")
4+
set(FENIX_DOCS_MAN "YES" CACHE BOOL "Option to disable man page generation for CI builds")
5+
set(FENIX_BRANCH "local" CACHE BOOL "Git branch being documented, or local if not building for Github Pages")
6+
7+
if(NOT DOXYGEN_FOUND)
8+
message(STATUS "Doxygen not found, `make docs` disabled")
9+
return()
10+
endif()
11+
12+
list(APPEND DOXYGEN_EXAMPLE_PATH markdown)
13+
list(APPEND DOXYGEN_IMAGE_PATH images)
14+
15+
set(DOXYGEN_USE_MDFILE_AS_MAINPAGE markdown/Introduction.md)
16+
set(DOXYGEN_LAYOUT_FILE DoxygenLayout.xml)
17+
set(DOXYGEN_OUTPUT_DIRECTORY ${FENIX_DOCS_OUTPUT})
18+
19+
set(DOXYGEN_GENERATE_MAN ${FENIX_DOCS_MAN})
20+
21+
set(DOXYGEN_QUIET YES)
22+
set(DOXYGEN_WARN_IF_UNDOCUMENTED NO)
23+
set(DOXYGEN_WARN_IF_DOC_ERROR YES)
24+
set(DOXYGEN_WARN_NO_PARAMDOC YES)
25+
set(DOXYGEN_SHOW_INCLUDE_FILES NO)
26+
set(DOXYGEN_WARN_IF_UNDOC_ENUM_VAL NO)
27+
28+
list(APPEND DOXYGEN_ALIASES "returnstatus=@return FENIX_SUCCESS if successful, any [return code](@ref ReturnCodes) otherwise.")
29+
list(APPEND DOXYGEN_ALIASES "unimplemented=@qualifier UNIMPLEMENTED @brief @htmlonly <span class=\\\"mlabel\\\"> @endhtmlonly UNIMPLEMENTED @htmlonly </span> @endhtmlonly")
30+
31+
add_subdirectory(html)
32+
33+
doxygen_add_docs(docs
34+
markdown/Introduction.md fake_init.h ../include ../src
35+
ALL
36+
COMMENT "Generate Fenix documentation")
37+
message(STATUS "Run `make docs` to build documentation")
38+
39+
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/man DESTINATION ${CMAKE_INSTALL_PREFIX})

0 commit comments

Comments
 (0)