Skip to content

Commit 744eaee

Browse files
alandefreitasalandefreitas
committed
docs: antora setup
1 parent 8460e1f commit 744eaee

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

@@ -218,7 +219,7 @@ source_group(TREE ${PROJECT_SOURCE_DIR}/source PREFIX "source" FILES ${SOURCES})
218219
#
219220
#-------------------------------------------------
220221

221-
if (BUILD_TESTING)
222+
if (MRDOX_BUILD_TESTS)
222223
file(GLOB_RECURSE TEST_SOURCES CONFIGURE_DEPENDS source/*.cpp source/*.hpp)
223224
enable_testing()
224225
add_test(NAME mrdox-test COMMAND mrdox --action test
@@ -260,6 +261,37 @@ if (BUILD_TESTING)
260261
endif()
261262
endif()
262263

264+
265+
#-------------------------------------------------
266+
#
267+
# Docs
268+
#
269+
#-------------------------------------------------
270+
271+
if (MRDOX_BUILD_DOCS)
272+
find_program(NPM_EXECUTABLE npm)
273+
find_program(NPX_EXECUTABLE npx)
274+
275+
if(NPM_EXECUTABLE AND NPX_EXECUTABLE)
276+
message(STATUS "NPM found: ${NPM_EXECUTABLE}")
277+
message(STATUS "NPX found: ${NPX_EXECUTABLE}")
278+
279+
set(DOCS_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/docs)
280+
set(DOCS_BUILD_DIR ${DOCS_SOURCE_DIR}/build/site)
281+
set(DOCS_INSTALL_DIR ${CMAKE_INSTALL_PREFIX}/doc/mrdox/html)
282+
283+
# Add custom target for generating documentation
284+
add_custom_target(generate_docs
285+
COMMAND ${NPM_EXECUTABLE} install
286+
COMMAND ${NPX_EXECUTABLE} antora local-antora-playbook.yml
287+
WORKING_DIRECTORY ${DOCS_SOURCE_DIR}
288+
COMMENT "Generating MrDox documentation"
289+
)
290+
else()
291+
message(WARNING "NPM or NPX not found. Unable to generate documentation.")
292+
endif()
293+
endif ()
294+
263295
#-------------------------------------------------
264296
#
265297
# Install
@@ -285,6 +317,14 @@ if (MRDOX_INSTALL)
285317
DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
286318
FILES_MATCHING PATTERN "*.[hic]pp")
287319

320+
# Set installation rules for generated documentation
321+
if (MRDOX_BUILD_DOCS)
322+
install(DIRECTORY ${DOCS_BUILD_DIR}
323+
DESTINATION ${DOCS_INSTALL_DIR}
324+
COMPONENT documentation
325+
)
326+
endif()
327+
288328
# Set variable where the cmake config is
289329
# https://cliutils.gitlab.io/modern-cmake/chapters/install/installing.html
290330
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)