Skip to content

Commit e0ce1f8

Browse files
Matthew-WhitlockMatthew-Whitlock
committed
Initial doxygen setup
Documentation Organize, setup versioned docs Deploy docs to Github pages Update doxygen header Use Doxygen 1.12.0 for github pages builds Improved Process Recovery docs writeup 'make doc' -> 'make docs'
1 parent f5447ef commit e0ce1f8

18 files changed

+1414
-50
lines changed

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

Lines changed: 54 additions & 0 deletions
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‎

Lines changed: 40 additions & 0 deletions
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‎

Lines changed: 20 additions & 15 deletions
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‎

Lines changed: 39 additions & 0 deletions
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)