Skip to content

Commit 14c58e9

Browse files
chandryanchandryan
committed
fix(doc): Antora build with MrDocs in the CI
1 parent d5167a7 commit 14c58e9

6 files changed

Lines changed: 163 additions & 38 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -288,3 +288,68 @@ jobs:
288288
run: |
289289
cd ../boost-root
290290
b2 -j3 libs/%LIBRARY%/test toolset=${{matrix.toolset}} cxxstd=${{matrix.cxxstd}} address-model=${{matrix.addrmd}} variant=debug,release embed-manifest-via=linker
291+
292+
antora:
293+
name: Antora docs
294+
strategy:
295+
matrix:
296+
include:
297+
- { name: Windows, os: windows-latest }
298+
- { name: Ubuntu, os: ubuntu-latest }
299+
- { name: macOS, os: macos-15 }
300+
runs-on: ${{ matrix.os }}
301+
defaults:
302+
run:
303+
shell: bash
304+
steps:
305+
- name: Install packages
306+
uses: alandefreitas/cpp-actions/package-install@v1.9.3
307+
with:
308+
apt-get: git cmake
309+
310+
- name: Clone Boost.MSM
311+
uses: actions/checkout@v4
312+
313+
- name: Clone Boost
314+
uses: alandefreitas/cpp-actions/boost-clone@v1.9.3
315+
id: boost-clone
316+
with:
317+
branch: ${{ (github.ref_name == 'master' && github.ref_name) || 'develop' }}
318+
boost-dir: ../boost-source
319+
scan-modules-dir: .
320+
scan-modules-ignore: msm
321+
322+
- uses: actions/setup-node@v4
323+
with:
324+
node-version: 18
325+
326+
- name: Setup Ninja
327+
if: runner.os == 'Windows'
328+
uses: seanmiddleditch/gha-setup-ninja@v5
329+
330+
- name: Build Antora docs
331+
env:
332+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
333+
run: |
334+
git config --global --add safe.directory "$(pwd)"
335+
336+
cd ..
337+
BOOST_SRC_DIR="$(pwd)/boost-source"
338+
export BOOST_SRC_DIR
339+
340+
cd msm
341+
cd doc
342+
bash ./build_antora.sh
343+
344+
# Antora returns zero even if it fails, so we check if the site directory exists.
345+
if [ ! -d "build" ]
346+
then
347+
echo "Antora build failed"
348+
exit 1
349+
fi
350+
351+
- name: Create Antora docs artifact
352+
uses: actions/upload-artifact@v4
353+
with:
354+
name: antora-docs-${{ matrix.name }}
355+
path: doc/build

‎CMakeLists.txt‎

Lines changed: 36 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -15,34 +15,48 @@ add_library(Boost::msm ALIAS boost_msm)
1515

1616
target_include_directories(boost_msm INTERFACE include)
1717

18+
set(BOOST_MSM_DEPENDENCIES
19+
Boost::any
20+
Boost::assert
21+
Boost::bind
22+
Boost::circular_buffer
23+
Boost::config
24+
Boost::core
25+
Boost::function
26+
Boost::fusion
27+
Boost::mp11
28+
Boost::mpl
29+
Boost::parameter
30+
Boost::phoenix
31+
Boost::preprocessor
32+
Boost::proto
33+
Boost::serialization
34+
Boost::tuple
35+
Boost::type_traits
36+
Boost::typeof)
37+
38+
if(BOOST_MSM_BUILD_MRDOCS AND DEFINED ENV{BOOST_SRC_DIR})
39+
set(BOOST_MSM_DEPENDENCIES_PLAIN "")
40+
foreach(dep ${BOOST_MSM_DEPENDENCIES})
41+
string(REPLACE "Boost::" "" dep_plain ${dep})
42+
list(APPEND BOOST_MSM_DEPENDENCIES_PLAIN ${dep_plain})
43+
endforeach()
44+
set(BOOST_INCLUDE_LIBRARIES ${BOOST_MSM_DEPENDENCIES_PLAIN})
45+
set(BOOST_EXCLUDE_LIBRARIES msm)
46+
# Exclude MSM's dependencies from compile_commands.json to reduce MrDocs runtime.
47+
set(CMAKE_EXPORT_COMPILE_COMMANDS OFF)
48+
add_subdirectory($ENV{BOOST_SRC_DIR} deps_/boost EXCLUDE_FROM_ALL)
49+
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
50+
endif()
51+
1852
if(CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
1953
set(BOOST_MSM_IS_ROOT ON)
2054
else()
2155
set(BOOST_MSM_IS_ROOT OFF)
2256
endif()
2357

24-
if(NOT BOOST_MSM_IS_ROOT)
25-
target_link_libraries(boost_msm
26-
INTERFACE
27-
Boost::any
28-
Boost::assert
29-
Boost::bind
30-
Boost::circular_buffer
31-
Boost::config
32-
Boost::core
33-
Boost::function
34-
Boost::fusion
35-
Boost::mp11
36-
Boost::mpl
37-
Boost::parameter
38-
Boost::phoenix
39-
Boost::preprocessor
40-
Boost::proto
41-
Boost::serialization
42-
Boost::tuple
43-
Boost::type_traits
44-
Boost::typeof
45-
)
58+
if(NOT BOOST_MSM_IS_ROOT OR (BOOST_MSM_BUILD_MRDOCS AND DEFINED ENV{BOOST_SRC_DIR}))
59+
target_link_libraries(boost_msm INTERFACE ${BOOST_MSM_DEPENDENCIES})
4660
else()
4761
# Boost 1.66 is the first version with Mp11
4862
find_package(Boost 1.66 REQUIRED COMPONENTS serialization)

‎doc/Makefile‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,15 @@
11

22
SOURCE:=$(shell find modules)
33

4-
build/lib/doc/robots.txt: $(SOURCE)
5-
npx antora --fetch local-playbook.yml --stacktrace
6-
74
.PHONY: build
8-
build : build/lib/doc/robots.txt
5+
build : build/lib/doc/msm/index.html
96

107
.PHONY: setup
118
setup:
129
npm install
1310
wget -q https://github.com/cppalliance/mrdocs/releases/download/v0.8.0/MrDocs-0.8.0-Linux.tar.xz -O mrdocs.tar.xz
1411
sudo tar -xJf mrdocs.tar.xz -C /usr/local --strip-components=1 MrDocs-0.8.0-Linux
1512
rm mrdocs.tar.xz
16-
git init && git commit --allow-empty -m init
1713

14+
build/lib/doc/msm/index.html: $(SOURCE)
15+
npx antora --fetch local-playbook.yml --stacktrace

‎doc/README.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,16 @@
1-
## Building the documentation locally
1+
# Building the documentation locally
22

33
Run the following commands once for the initial setup:
44

55
- Make sure nodejs (LTS version >= 16.0.0) & npm are installed: `sudo apt install nodejs npm`
66
- Make sure you are in the doc folder: `cd doc`
77
- Run the Make target for the setup: `make setup`
88

9-
The setup creates a pseudo-repository in the doc folder:
10-
Antora requires the doc sources to be located within a git repository, but it cannot recognize git submodules. By setting up a pseudo-repository, the local documentation build works when MSM is used as a standalone repo as well as when MSM is opened from a submodule path within the Boost super-project.
9+
Antora requires the doc sources to be located within a git repository, but it cannot recognize git submodules.
10+
You can set up a pseudo-repository with `git init && git commit --allow-empty -m init` to make the local documentation build work when MSM is opened from a submodule path within the Boost super-project.
1111

1212
After the initial setup is done, build the the documentation with `make build`.
1313

1414
If you are not interested in viewing the generated API reference, you can speed up the documenation build with the ENV `ANTORA_SKIP_CPP_REFERENCE=1`.
15+
16+
The Antora Cpp reference extension will clone the complete Boost repo to a cache folder. If you want to use an existing folder instead, set up an ENV `BOOST_SRC_DIR` to point to it.

‎doc/build_antora.sh‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
#
2+
# Copyright (c) 2023 Alan de Freitas (alandefreitas@gmail.com)
3+
#
4+
# Distributed under the Boost Software License, Version 1.0. (See accompanying
5+
# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6+
#
7+
8+
set -xe
9+
10+
SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
11+
cd "$SCRIPT_DIR"
12+
13+
if [ -z "${BOOST_SRC_DIR:-}" ]; then
14+
CANDIDATE=$( cd "$SCRIPT_DIR/../../.." 2>/dev/null && pwd )
15+
if [ -n "$CANDIDATE" ]; then
16+
BOOST_SRC_DIR_IS_VALID=ON
17+
for F in "CMakeLists.txt" "Jamroot" "boost-build.jam" "bootstrap.sh" "libs"; do
18+
if [ ! -e "$CANDIDATE/$F" ]; then
19+
BOOST_SRC_DIR_IS_VALID=OFF
20+
break
21+
fi
22+
done
23+
if [ "$BOOST_SRC_DIR_IS_VALID" = "ON" ]; then
24+
export BOOST_SRC_DIR="$CANDIDATE"
25+
echo "Using BOOST_SRC_DIR=$BOOST_SRC_DIR"
26+
fi
27+
fi
28+
fi
29+
30+
if [ $# -eq 0 ]
31+
then
32+
echo "No playbook supplied, using default playbook"
33+
PLAYBOOK="local-playbook.yml"
34+
else
35+
PLAYBOOK=$1
36+
fi
37+
38+
echo "Building documentation with Antora..."
39+
echo "Installing npm dependencies..."
40+
npm ci
41+
42+
echo "Building docs in custom dir..."
43+
PATH="$(pwd)/node_modules/.bin:${PATH}"
44+
export PATH
45+
npx antora --clean --fetch "$PLAYBOOK" --stacktrace --log-level all
46+
echo "Done"

‎doc/local-playbook.yml‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -54,12 +54,12 @@ antora:
5454
- 'boost::'
5555
- require: '@cppalliance/antora-downloads-extension'
5656
- require: '@cppalliance/antora-cpp-reference-extension'
57-
# dependencies:
58-
# - name: 'boost'
59-
# repo: 'https://github.com/boostorg/boost.git'
60-
# tag: 'develop'
61-
# variable: 'BOOST_SRC_DIR'
62-
# system-env: 'BOOST_SRC_DIR'
57+
dependencies:
58+
- name: 'boost'
59+
repo: 'https://github.com/boostorg/boost.git'
60+
tag: 'develop'
61+
variable: 'BOOST_SRC_DIR'
62+
system-env: 'BOOST_SRC_DIR'
6363

6464
asciidoc:
6565
attributes:
@@ -77,8 +77,8 @@ runtime:
7777
# Libraries that support Antora should be included here
7878
content:
7979
sources:
80-
- url: .
81-
start_path: .
80+
- url: ..
81+
start_path: doc
8282
edit_url: 'https://github.com/boostorg/msm/edit/develop/{path}'
8383

8484
ui:

0 commit comments

Comments
 (0)