mirror of
https://github.com/boostorg/msm.git
synced 2026-07-21 13:23:45 +00:00
fix(doc): Antora build with MrDocs in the CI
This commit is contained in:
Christian Granzin
committed by
Christian Granzin
Christian Granzin
parent
d5167a7902
commit
14c58e9b33
@@ -288,3 +288,68 @@ jobs:
|
||||
run: |
|
||||
cd ../boost-root
|
||||
b2 -j3 libs/%LIBRARY%/test toolset=${{matrix.toolset}} cxxstd=${{matrix.cxxstd}} address-model=${{matrix.addrmd}} variant=debug,release embed-manifest-via=linker
|
||||
|
||||
antora:
|
||||
name: Antora docs
|
||||
strategy:
|
||||
matrix:
|
||||
include:
|
||||
- { name: Windows, os: windows-latest }
|
||||
- { name: Ubuntu, os: ubuntu-latest }
|
||||
- { name: macOS, os: macos-15 }
|
||||
runs-on: ${{ matrix.os }}
|
||||
defaults:
|
||||
run:
|
||||
shell: bash
|
||||
steps:
|
||||
- name: Install packages
|
||||
uses: alandefreitas/cpp-actions/package-install@v1.9.3
|
||||
with:
|
||||
apt-get: git cmake
|
||||
|
||||
- name: Clone Boost.MSM
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Clone Boost
|
||||
uses: alandefreitas/cpp-actions/boost-clone@v1.9.3
|
||||
id: boost-clone
|
||||
with:
|
||||
branch: ${{ (github.ref_name == 'master' && github.ref_name) || 'develop' }}
|
||||
boost-dir: ../boost-source
|
||||
scan-modules-dir: .
|
||||
scan-modules-ignore: msm
|
||||
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 18
|
||||
|
||||
- name: Setup Ninja
|
||||
if: runner.os == 'Windows'
|
||||
uses: seanmiddleditch/gha-setup-ninja@v5
|
||||
|
||||
- name: Build Antora docs
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
run: |
|
||||
git config --global --add safe.directory "$(pwd)"
|
||||
|
||||
cd ..
|
||||
BOOST_SRC_DIR="$(pwd)/boost-source"
|
||||
export BOOST_SRC_DIR
|
||||
|
||||
cd msm
|
||||
cd doc
|
||||
bash ./build_antora.sh
|
||||
|
||||
# Antora returns zero even if it fails, so we check if the site directory exists.
|
||||
if [ ! -d "build" ]
|
||||
then
|
||||
echo "Antora build failed"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
- name: Create Antora docs artifact
|
||||
uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: antora-docs-${{ matrix.name }}
|
||||
path: doc/build
|
||||
|
||||
+36
-22
@@ -15,34 +15,48 @@ add_library(Boost::msm ALIAS boost_msm)
|
||||
|
||||
target_include_directories(boost_msm INTERFACE include)
|
||||
|
||||
set(BOOST_MSM_DEPENDENCIES
|
||||
Boost::any
|
||||
Boost::assert
|
||||
Boost::bind
|
||||
Boost::circular_buffer
|
||||
Boost::config
|
||||
Boost::core
|
||||
Boost::function
|
||||
Boost::fusion
|
||||
Boost::mp11
|
||||
Boost::mpl
|
||||
Boost::parameter
|
||||
Boost::phoenix
|
||||
Boost::preprocessor
|
||||
Boost::proto
|
||||
Boost::serialization
|
||||
Boost::tuple
|
||||
Boost::type_traits
|
||||
Boost::typeof)
|
||||
|
||||
if(BOOST_MSM_BUILD_MRDOCS AND DEFINED ENV{BOOST_SRC_DIR})
|
||||
set(BOOST_MSM_DEPENDENCIES_PLAIN "")
|
||||
foreach(dep ${BOOST_MSM_DEPENDENCIES})
|
||||
string(REPLACE "Boost::" "" dep_plain ${dep})
|
||||
list(APPEND BOOST_MSM_DEPENDENCIES_PLAIN ${dep_plain})
|
||||
endforeach()
|
||||
set(BOOST_INCLUDE_LIBRARIES ${BOOST_MSM_DEPENDENCIES_PLAIN})
|
||||
set(BOOST_EXCLUDE_LIBRARIES msm)
|
||||
# Exclude MSM's dependencies from compile_commands.json to reduce MrDocs runtime.
|
||||
set(CMAKE_EXPORT_COMPILE_COMMANDS OFF)
|
||||
add_subdirectory($ENV{BOOST_SRC_DIR} deps_/boost EXCLUDE_FROM_ALL)
|
||||
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
|
||||
endif()
|
||||
|
||||
if(CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
|
||||
set(BOOST_MSM_IS_ROOT ON)
|
||||
else()
|
||||
set(BOOST_MSM_IS_ROOT OFF)
|
||||
endif()
|
||||
|
||||
if(NOT BOOST_MSM_IS_ROOT)
|
||||
target_link_libraries(boost_msm
|
||||
INTERFACE
|
||||
Boost::any
|
||||
Boost::assert
|
||||
Boost::bind
|
||||
Boost::circular_buffer
|
||||
Boost::config
|
||||
Boost::core
|
||||
Boost::function
|
||||
Boost::fusion
|
||||
Boost::mp11
|
||||
Boost::mpl
|
||||
Boost::parameter
|
||||
Boost::phoenix
|
||||
Boost::preprocessor
|
||||
Boost::proto
|
||||
Boost::serialization
|
||||
Boost::tuple
|
||||
Boost::type_traits
|
||||
Boost::typeof
|
||||
)
|
||||
if(NOT BOOST_MSM_IS_ROOT OR (BOOST_MSM_BUILD_MRDOCS AND DEFINED ENV{BOOST_SRC_DIR}))
|
||||
target_link_libraries(boost_msm INTERFACE ${BOOST_MSM_DEPENDENCIES})
|
||||
else()
|
||||
# Boost 1.66 is the first version with Mp11
|
||||
find_package(Boost 1.66 REQUIRED COMPONENTS serialization)
|
||||
|
||||
+3
-5
@@ -1,11 +1,8 @@
|
||||
|
||||
SOURCE:=$(shell find modules)
|
||||
|
||||
build/lib/doc/robots.txt: $(SOURCE)
|
||||
npx antora --fetch local-playbook.yml --stacktrace
|
||||
|
||||
.PHONY: build
|
||||
build : build/lib/doc/robots.txt
|
||||
build : build/lib/doc/msm/index.html
|
||||
|
||||
.PHONY: setup
|
||||
setup:
|
||||
@@ -13,5 +10,6 @@ setup:
|
||||
wget -q https://github.com/cppalliance/mrdocs/releases/download/v0.8.0/MrDocs-0.8.0-Linux.tar.xz -O mrdocs.tar.xz
|
||||
sudo tar -xJf mrdocs.tar.xz -C /usr/local --strip-components=1 MrDocs-0.8.0-Linux
|
||||
rm mrdocs.tar.xz
|
||||
git init && git commit --allow-empty -m init
|
||||
|
||||
build/lib/doc/msm/index.html: $(SOURCE)
|
||||
npx antora --fetch local-playbook.yml --stacktrace
|
||||
|
||||
+5
-3
@@ -1,4 +1,4 @@
|
||||
## Building the documentation locally
|
||||
# Building the documentation locally
|
||||
|
||||
Run the following commands once for the initial setup:
|
||||
|
||||
@@ -6,9 +6,11 @@ Run the following commands once for the initial setup:
|
||||
- Make sure you are in the doc folder: `cd doc`
|
||||
- Run the Make target for the setup: `make setup`
|
||||
|
||||
The setup creates a pseudo-repository in the doc folder:
|
||||
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.
|
||||
Antora requires the doc sources to be located within a git repository, but it cannot recognize git submodules.
|
||||
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.
|
||||
|
||||
After the initial setup is done, build the the documentation with `make build`.
|
||||
|
||||
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`.
|
||||
|
||||
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.
|
||||
|
||||
Executable
+46
@@ -0,0 +1,46 @@
|
||||
#
|
||||
# Copyright (c) 2023 Alan de Freitas (alandefreitas@gmail.com)
|
||||
#
|
||||
# Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
||||
#
|
||||
|
||||
set -xe
|
||||
|
||||
SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
|
||||
cd "$SCRIPT_DIR"
|
||||
|
||||
if [ -z "${BOOST_SRC_DIR:-}" ]; then
|
||||
CANDIDATE=$( cd "$SCRIPT_DIR/../../.." 2>/dev/null && pwd )
|
||||
if [ -n "$CANDIDATE" ]; then
|
||||
BOOST_SRC_DIR_IS_VALID=ON
|
||||
for F in "CMakeLists.txt" "Jamroot" "boost-build.jam" "bootstrap.sh" "libs"; do
|
||||
if [ ! -e "$CANDIDATE/$F" ]; then
|
||||
BOOST_SRC_DIR_IS_VALID=OFF
|
||||
break
|
||||
fi
|
||||
done
|
||||
if [ "$BOOST_SRC_DIR_IS_VALID" = "ON" ]; then
|
||||
export BOOST_SRC_DIR="$CANDIDATE"
|
||||
echo "Using BOOST_SRC_DIR=$BOOST_SRC_DIR"
|
||||
fi
|
||||
fi
|
||||
fi
|
||||
|
||||
if [ $# -eq 0 ]
|
||||
then
|
||||
echo "No playbook supplied, using default playbook"
|
||||
PLAYBOOK="local-playbook.yml"
|
||||
else
|
||||
PLAYBOOK=$1
|
||||
fi
|
||||
|
||||
echo "Building documentation with Antora..."
|
||||
echo "Installing npm dependencies..."
|
||||
npm ci
|
||||
|
||||
echo "Building docs in custom dir..."
|
||||
PATH="$(pwd)/node_modules/.bin:${PATH}"
|
||||
export PATH
|
||||
npx antora --clean --fetch "$PLAYBOOK" --stacktrace --log-level all
|
||||
echo "Done"
|
||||
@@ -54,12 +54,12 @@ antora:
|
||||
- 'boost::'
|
||||
- require: '@cppalliance/antora-downloads-extension'
|
||||
- require: '@cppalliance/antora-cpp-reference-extension'
|
||||
# dependencies:
|
||||
# - name: 'boost'
|
||||
# repo: 'https://github.com/boostorg/boost.git'
|
||||
# tag: 'develop'
|
||||
# variable: 'BOOST_SRC_DIR'
|
||||
# system-env: 'BOOST_SRC_DIR'
|
||||
dependencies:
|
||||
- name: 'boost'
|
||||
repo: 'https://github.com/boostorg/boost.git'
|
||||
tag: 'develop'
|
||||
variable: 'BOOST_SRC_DIR'
|
||||
system-env: 'BOOST_SRC_DIR'
|
||||
|
||||
asciidoc:
|
||||
attributes:
|
||||
@@ -77,8 +77,8 @@ runtime:
|
||||
# Libraries that support Antora should be included here
|
||||
content:
|
||||
sources:
|
||||
- url: .
|
||||
start_path: .
|
||||
- url: ..
|
||||
start_path: doc
|
||||
edit_url: 'https://github.com/boostorg/msm/edit/develop/{path}'
|
||||
|
||||
ui:
|
||||
|
||||
Reference in New Issue
Block a user