Skip to content

Commit 438dde4

Browse files
alandefreitasalandefreitas
committed
docs: antora setup
1 parent 616773e commit 438dde4

20 files changed

+3326
-48
lines changed

‎.github/workflows/ci.yml

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,53 @@ jobs:
102102
run:
103103
shell: bash
104104

105+
name: Publish docs
106+
timeout-minutes: 30
107+
runs-on: ubuntu-22.04
108+
permissions:
109+
contents: write
110+
111+
steps:
112+
- uses: actions/checkout@v3
113+
114+
- name: Install Node.js
115+
uses: actions/setup-node@v3
116+
with:
117+
node-version: '18'
118+
119+
- name: Install Antora
120+
working-directory: docs
121+
run: |
122+
npm install
123+
124+
- name: Generate Site
125+
working-directory: docs
126+
run: |
127+
master_antora_exists=$(curl --silent --fail --head https://github.com/cppalliance/mrdox/blob/master/docs/antora.yml >/dev/null && echo "true" || echo "false")
128+
develop_antora_exists=$(curl --silent --fail --head https://github.com/cppalliance/mrdox/blob/develop/docs/antora.yml >/dev/null && echo "true" || echo "false")
129+
if [ "$master_antora_exists" == "true" ] && [ "$develop_antora_exists" == "true" ]; then
130+
# Antora is set up in both master and develop: render complete playbook
131+
npx antora antora-playbook.yml
132+
else
133+
# Antora is not set up in master and develop yet: render local playbook while integration is not complete
134+
# The local playbook is used for local development and for the documentation included in the release
135+
npx antora local-antora-playbook.yml
136+
fi
137+
138+
- name: Publish to GitHub Pages
139+
uses: peaceiris/actions-gh-pages@v3
140+
with:
141+
github_token: ${{ secrets.GITHUB_TOKEN }}
142+
publish_dir: docs/build/site
143+
force_orphan: true
144+
145+
releases:
146+
needs: build
147+
if: ${{ github.event_name == 'push' && (contains(fromJSON('["master", "develop"]'), github.ref_name) || startsWith(github.ref, 'refs/tags/')) }}
148+
defaults:
149+
run:
150+
shell: bash
151+
105152
name: Create Release Packages
106153
timeout-minutes: 120
107154
runs-on: ubuntu-22.04

‎.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,5 @@
88
/test-files/py
99
/test-files/**/*.adoc
1010
/test-files/**/*.bad.xml
11+
docs/node_modules
12+
docs/build

‎CMakeLists.txt

Lines changed: 41 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ include(GNUInstallDirs)
3636

3737
option(MRDOX_BUILD_TESTS "Build tests" ${BUILD_TESTING})
3838
option(MRDOX_BUILD_SHARED "Link shared" OFF)
39+
option(MRDOX_BUILD_DOCS "Configure install target" OFF)
3940
option(MRDOX_INSTALL "Configure install target" ON)
4041
option(MRDOX_PACKAGE "Build install package" ON)
4142

@@ -186,7 +187,7 @@ source_group(TREE ${PROJECT_SOURCE_DIR}/source PREFIX "source" FILES ${SOURCES})
186187
#
187188
#-------------------------------------------------
188189

189-
if (BUILD_TESTING)
190+
if (MRDOX_BUILD_TESTS)
190191
file(GLOB_RECURSE TEST_SOURCES CONFIGURE_DEPENDS source/*.cpp source/*.hpp)
191192
enable_testing()
192193
add_test(NAME mrdox-test COMMAND mrdox --action test
@@ -228,6 +229,37 @@ if (BUILD_TESTING)
228229
endif()
229230
endif()
230231

232+
233+
#-------------------------------------------------
234+
#
235+
# Docs
236+
#
237+
#-------------------------------------------------
238+
239+
if (MRDOX_BUILD_DOCS)
240+
find_program(NPM_EXECUTABLE npm)
241+
find_program(NPX_EXECUTABLE npx)
242+
243+
if(NPM_EXECUTABLE AND NPX_EXECUTABLE)
244+
message(STATUS "NPM found: ${NPM_EXECUTABLE}")
245+
message(STATUS "NPX found: ${NPX_EXECUTABLE}")
246+
247+
set(DOCS_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/docs)
248+
set(DOCS_BUILD_DIR ${DOCS_SOURCE_DIR}/build/site)
249+
set(DOCS_INSTALL_DIR ${CMAKE_INSTALL_PREFIX}/doc/mrdox/html)
250+
251+
# Add custom target for generating documentation
252+
add_custom_target(generate_docs
253+
COMMAND ${NPM_EXECUTABLE} install
254+
COMMAND ${NPX_EXECUTABLE} antora local-antora-playbook.yml
255+
WORKING_DIRECTORY ${DOCS_SOURCE_DIR}
256+
COMMENT "Generating MrDox documentation"
257+
)
258+
else()
259+
message(WARNING "NPM or NPX not found. Unable to generate documentation.")
260+
endif()
261+
endif ()
262+
231263
#-------------------------------------------------
232264
#
233265
# Install
@@ -253,6 +285,14 @@ if (MRDOX_INSTALL)
253285
DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
254286
FILES_MATCHING PATTERN "*.[hic]pp")
255287

288+
# Set installation rules for generated documentation
289+
if (MRDOX_BUILD_DOCS)
290+
install(DIRECTORY ${DOCS_BUILD_DIR}
291+
DESTINATION ${DOCS_INSTALL_DIR}
292+
COMPONENT documentation
293+
)
294+
endif()
295+
256296
# Set variable where the cmake config is
257297
# https://cliutils.gitlab.io/modern-cmake/chapters/install/installing.html
258298
set(CONFIG_INSTALL_DIR ${CMAKE_INSTALL_LIBDIR}/cmake/mrdox)

‎NOTES.adoc

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

‎docs/.asciidoctorconfig

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
:linkcss:
2+
:stylesdir: https://cppalliance.github.io/mrdox/_/stylesheets
3+
:stylesheet: site.css

‎docs/antora-playbook.yml

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# npm install
2+
# npx antora --fetch antora-playbook.yml
3+
site:
4+
title: MrDox
5+
url: https://cppalliance.github.io/mrdox/
6+
start_page: mrdox::index.adoc
7+
robots: allow
8+
keys:
9+
repo_url: 'https://github.com/cppalliance/mrdox'
10+
11+
content:
12+
branches: [ master, develop ]
13+
tags: [ v* ]
14+
edit_url: 'https://github.com/cppalliance/mrdox/edit/{refname}/{path}'
15+
sources:
16+
- url: https://github.com/cppalliance/mrdox.git
17+
start_path: docs
18+
edit_url: 'https://github.com/cppalliance/mrdox/edit/{refname}/{path}'
19+
20+
ui:
21+
bundle:
22+
url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
23+
snapshot: true
24+
25+
antora:
26+
extensions:
27+
- require: '@antora/lunr-extension' # https://gitlab.com/antora/antora-lunr-extension
28+
index_latest_only: true
29+

‎docs/antora.yml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
name: mrdox
2+
title: MrDox
3+
version: true
4+
start_page: index.adoc
5+
asciidoc:
6+
attributes:
7+
source-language: asciidoc@
8+
table-caption: false
9+
nav:
10+
- modules/ROOT/nav.adoc

‎docs/design-notes.adoc

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

‎docs/local-antora-playbook.yml

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# npm install
2+
# npx antora --fetch local-antora-playbook.yml
3+
site:
4+
title: MrDox
5+
url: https://cppalliance.github.io/mrdox/
6+
start_page: mrdox::index.adoc
7+
robots: allow
8+
keys:
9+
repo_url: 'https://github.com/cppalliance/mrdox'
10+
11+
content:
12+
sources:
13+
- url: ..
14+
start_path: docs
15+
edit_url: 'https://github.com/cppalliance/mrdox/edit/{refname}/{path}'
16+
17+
ui:
18+
bundle:
19+
url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
20+
snapshot: true
21+
22+
antora:
23+
extensions:
24+
- require: '@antora/lunr-extension' # https://gitlab.com/antora/antora-lunr-extension
25+
index_latest_only: true
26+

‎docs/modules/ROOT/images/MrDoxBanner.png

294 KB
Loading

0 commit comments

Comments
 (0)