Skip to content

Commit ecf6a14

Browse files
jll63jll63
committed
adopt antora and mrdocs
1 parent a39e9a3 commit ecf6a14

File tree

8 files changed

+3176
-0
lines changed

8 files changed

+3176
-0
lines changed

‎doc/.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
temp
2+
out.txt
3+
qbk/reference.qbk
4+
node_modules
5+
build

‎doc/antora.yml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
#
2+
# Copyright (c) 2023 Alan de Freitas ([email protected])
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+
# Official repository: https://github.com/boostorg/openmethod
8+
#
9+
10+
name: openmethod
11+
version: ~
12+
title: Boost.OpenMethod
13+
start_page: index.adoc
14+
asciidoc:
15+
attributes:
16+
source-language: asciidoc@
17+
table-caption: false
18+
nav:
19+
- modules/ROOT/nav.adoc
20+
ext:
21+
cpp-reference:
22+
config: doc/mrdocs.yml
23+
cpp-tagfiles:
24+
files:
25+
- file: ./doc/tagfiles/boost-openmethod-doxygen.tag.xml
26+
base_url: 'xref:reference:'
27+
- file: ./doc/tagfiles/boost-system-doxygen.tag.xml
28+
base_url: https://www.boost.org/doc/libs/master/libs/system/doc/html/
29+
- file: ./doc/tagfiles/boost-core-doxygen.tag.xml
30+
base_url: https://www.boost.org/doc/libs/master/libs/core/doc/html/
31+
- file: ./doc/tagfiles/boost-filesystem-doxygen.tag.xml
32+
base_url: https://www.boost.org/doc/libs/master/libs/filesystem/doc/
33+
using-namespaces:
34+
- boost::openmethod
35+
- boost::openmethod::policies
36+
- boost::openmethod::aliases

‎doc/build_antora.sh‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
#
2+
# Copyright (c) 2023 Alan de Freitas ([email protected])
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+
# Official repository: https://github.com/boostorg/url
8+
#
9+
10+
set -xe
11+
12+
if [ $# -eq 0 ]
13+
then
14+
echo "No playbook supplied, using default playbook"
15+
PLAYBOOK="local-playbook.yml"
16+
else
17+
PLAYBOOK=$1
18+
fi
19+
20+
echo "Building documentation with Antora..."
21+
echo "Installing npm dependencies..."
22+
npm ci
23+
24+
echo "Building docs in custom dir..."
25+
PATH="$(pwd)/node_modules/.bin:${PATH}"
26+
export PATH
27+
npx antora --clean --fetch "$PLAYBOOK" --stacktrace --log-level all
28+
echo "Done"
29+

‎doc/index.html‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
<html>
2+
<head>
3+
<title>Boost.OpenMethod</title>
4+
<meta http-equiv="refresh" content="0; URL=../../../doc/antora/openmethod/index.html">
5+
</head>
6+
<body>
7+
Automatic redirection failed, please go to
8+
<a href="../../../doc/antora/openmethod/index.html">../../../doc/antora/openmethod/index.html</a>
9+
<hr>
10+
<tt>
11+
Boost.OpenMethod<br>
12+
<br>
13+
Copyright&nbsp;(C)&nbsp;2025&nbsp;Jean-Louis&nbsp;Leroy<br>
14+
<br>
15+
Distributed under the Boost Software License, Version 1.0.
16+
(See accompanying file LICENSE_1_0.txt or copy at
17+
<a href=http://www.boost.org/LICENSE_1_0.txt>http://www.boost.org/LICENSE_1_0.txt</a>) <br>
18+
<br>
19+
</tt>
20+
</body>
21+
</html>

‎doc/local-playbook.yml‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
#
2+
# Copyright (c) 2023 Alan de Freitas ([email protected])
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+
# Official repository: https://github.com/boostorg/openmethod
8+
#
9+
10+
# An antora playbook used for local development
11+
# The playbook includes Boost.OpenMethod as its only component
12+
13+
site:
14+
title: Boost.OpenMethod
15+
url: https://antora.cppalliance.org/develop/lib/doc
16+
start_page: openmethod::index.adoc
17+
robots: allow
18+
keys:
19+
repo_url: 'https://github.com/boostorg/openmethod'
20+
21+
content:
22+
sources:
23+
- url: ..
24+
start_path: doc
25+
edit_url: 'https://github.com/boostorg/openmethod/edit/{refname}/{path}'
26+
27+
ui:
28+
bundle:
29+
url: https://github.com/boostorg/website-v2-docs/releases/download/ui-master/ui-bundle.zip
30+
snapshot: true
31+
32+
antora:
33+
extensions:
34+
- require: '@antora/lunr-extension' # https://gitlab.com/antora/antora-lunr-extension
35+
index_latest_only: true
36+
- require: '@cppalliance/antora-cpp-tagfiles-extension'
37+
cpp-tagfiles:
38+
using-namespaces:
39+
- 'boost::'
40+
- require: '@cppalliance/antora-cpp-reference-extension'
41+
dependencies:
42+
- name: 'boost'
43+
repo: 'https://github.com/boostorg/boost.git'
44+
tag: 'develop'
45+
variable: 'BOOST_SRC_DIR'
46+
system-env: 'BOOST_SRC_DIR'
47+
48+
asciidoc:
49+
attributes:
50+
# Enable pagination
51+
page-pagination: ''
52+
extensions:
53+
- '@cppalliance/asciidoctor-boost-links'
54+
- '@asciidoctor/tabs'

‎doc/mrdocs.yml‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Input
2+
source-root: ..
3+
# Directories that contain documented source files
4+
input:
5+
- ../include
6+
# Patterns to filter out the source-files in the directories
7+
file-patterns:
8+
- '*.hpp'
9+
exclude:
10+
- '../include/boost/url/impl'
11+
- '../include/boost/url/grammar/impl'
12+
- '../include/boost/url/rfc/impl'
13+
14+
# Filters
15+
include-symbols:
16+
- 'boost::urls::**'
17+
see-below:
18+
- 'boost::urls::format_arg'
19+
- 'boost::urls::named_arg'
20+
- 'boost::urls::see_below'
21+
- 'boost::urls::*_t'
22+
- 'boost::urls::grammar::see_below'
23+
- 'boost::urls::string_token::see_below'
24+
- 'boost::urls::decode_view::iterator'
25+
- 'boost::urls::params_base::iterator'
26+
- 'boost::urls::params_encoded_base::iterator'
27+
- 'boost::urls::segments_base::iterator'
28+
- 'boost::urls::segments_encoded_base::iterator'
29+
implementation-defined:
30+
- 'boost::urls::detail'
31+
- 'boost::urls::**::detail'
32+
- 'boost::urls::*_unsafe'
33+
- 'boost::urls::make_error_code'
34+
- 'boost::urls::make_void'
35+
- 'boost::urls::implementation_defined'
36+
- 'boost::urls::grammar::implementation_defined'
37+
- 'boost::urls::string_token::implementation_defined'
38+
- 'boost::urls::grammar::*_t'
39+
- 'boost::urls::grammar::make_error_*'
40+
- 'boost::urls::grammar::operator_*'
41+
- 'boost::urls::string_token::*_t'
42+
exclude-symbols:
43+
- 'boost::urls::void_t'
44+
45+
# Metadata Extraction
46+
private-bases: false
47+
48+
# Generator
49+
generate: adoc
50+
base-url: https://www.github.com/boostorg/url/blob/develop/ # boost/url/url_view.hpp
51+
52+
# Style
53+
verbose: true
54+
multipage: true
55+
56+
# The target for MrDocs simply includes all symbols defined in all
57+
# headers with the appropriate compilation options.
58+
# Nothing else should be included in the MrDocs configuration or
59+
# would be useful to MrDocs.
60+
#
61+
# This single source file not only includes all symbols (the source
62+
# files do not collectively include all headers) but also makes MrDocs
63+
# run much faster than relying on the entire library.
64+
#
65+
# The time to extract the declarations went from ~8m6s to ~3s in our
66+
# experiments: a 162x speedup while including all symbols!
67+
#
68+
# In practice, this special target is simply emulating the
69+
# default behavior of the standardese tool with MrDocs, which
70+
# requires the user to clearly specify the targets via the
71+
# compilation database.
72+
#
73+
# The BOOST_URL_MRDOCS_BUILD=ON is the only option we usually need
74+
# here.
75+
# The other options are set just to ensure other targets are
76+
# ignored even if these options are set as ON in the cache.
77+
#
78+
cmake: '-D BOOST_URL_MRDOCS_BUILD=ON -D CMAKE_CXX_STANDARD=20 -D BOOST_URL_BUILD_FUZZERS=OFF -D BOOST_URL_BUILD_EXAMPLES=OFF -D BOOST_URL_BUILD_TESTS=OFF -D BUILD_TESTING=OFF'

0 commit comments

Comments
 (0)