Skip to content

Commit 441f060

Browse files
dbastondbaston
committed
Docs: Build using CMake
1 parent fbcdb64 commit 441f060

File tree

9 files changed

+179
-1431
lines changed

9 files changed

+179
-1431
lines changed

‎.github/workflows/code_checks.yml

-12
Original file line numberDiff line numberDiff line change
@@ -164,18 +164,6 @@ jobs:
164164
- uses: actions/setup-python@42375524e23c412d93fb67b49958b491fce71c38 # v5.4.0
165165
- uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd # v3.0.1
166166

167-
doxygen:
168-
runs-on: ubuntu-latest
169-
container: ghcr.io/osgeo/proj-docs
170-
steps:
171-
- name: Checkout
172-
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
173-
174-
- name: Run doxygen
175-
run: |
176-
cd doc
177-
make doxygen_check_warnings
178-
179167
other_checks:
180168
runs-on: ubuntu-24.04
181169
steps:

‎.github/workflows/doc_checks.yml

+23-31
Original file line numberDiff line numberDiff line change
@@ -21,52 +21,44 @@ jobs:
2121
runs-on: ubuntu-latest
2222
strategy:
2323
fail-fast: true
24-
container: ghcr.io/osgeo/proj-docs
24+
container: ubuntu:24.04
2525

2626
steps:
2727
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
2828
- name: Setup environment
2929
shell: bash -l {0}
30+
env:
31+
DEBIAN_FRONTEND: noninteractive
3032
run: |
3133
apt update
32-
apt install -y libproj-dev swig
33-
PYTHON_CMD=python3 && $PYTHON_CMD -m pip install -r doc/requirements.txt
34-
PYTHON_CMD=python3 && $PYTHON_CMD -m pip install numpy setuptools
35-
pushd .
34+
apt install -y g++ cmake doxygen enchant-2 python3 python3-dev python3-pip python3-venv libproj-dev swig
35+
python3 -m venv create doc_env
36+
. doc_env/bin/activate
37+
python3 -m pip install -r doc/requirements.txt
38+
echo PATH=$PATH >> $GITHUB_ENV
39+
40+
- name: Build GDAL
41+
shell: bash -l {0}
42+
run: |
3643
mkdir build
3744
cd build
38-
export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
3945
cmake .. \
40-
-DCMAKE_BUILD_TYPE=Release \
41-
-DCMAKE_INSTALL_PREFIX=/usr \
46+
-DCMAKE_BUILD_TYPE=Debug \
4247
-DBUILD_APPS=ON \
43-
-DBUILD_TESTING=OFF \
48+
-DBUILD_DOCS=ON \
49+
-DBUILD_TESTING=ON \
4450
-DGDAL_BUILD_OPTIONAL_DRIVERS=OFF \
4551
-DOGR_BUILD_OPTIONAL_DRIVERS=OFF
4652
cmake --build . -j$(nproc)
47-
cmake --install .
48-
# With the new ghcr.io/osgeo/proj-docs image based on Ubuntu 24.04
49-
# a venv is activated. The above does not install the
50-
# Python bindings into it (and the ones in the system are not found
51-
# without overriding PYTHONPATH), so do it through pip install
52-
cd swig/python
53-
python3 setup.py sdist
54-
cp dist/* /tmp/gdal.tar.gz
55-
PYTHON_CMD=python3 && $PYTHON_CMD -m pip install /tmp/gdal.tar.gz
56-
ldconfig
57-
popd
58-
59-
- name: Update components
60-
shell: bash -l {0}
61-
run: |
62-
PYTHON_CMD=python3 && $PYTHON_CMD -m pip install -U "sphinx-rtd-theme>=3.0.0" "sphinxcontrib-spelling>=8.0.0"
6353
6454
- name: Print versions
6555
shell: bash -l {0}
6656
run: |
57+
which python3
6758
python3 --version
6859
sphinx-build --version
69-
PYTHON_CMD=python3 && $PYTHON_CMD -m pip list --not-required --format=columns
60+
python3 -m pip list --not-required --format=columns
61+
7062
- name: Lint .rst files
7163
shell: bash -l {0}
7264
run: |
@@ -79,11 +71,11 @@ jobs:
7971
- name: Doxygen
8072
shell: bash -l {0}
8173
run: |
82-
mkdir -p doc/build
83-
doxygen Doxyfile
74+
cmake --build . --target doxygen_xml
75+
working-directory: build
8476
- name: Spelling
8577
shell: bash -l {0}
8678
run: |
87-
sed -i '/html_extra_path/d' source/conf.py # avoid WARNING: html_extra_path entry '../build/html_extra' is placed inside outdir
88-
make spelling
89-
working-directory: ./doc
79+
python3 -c 'from osgeo import gdal'
80+
ctest -V -R spelling --output-on-failure
81+
working-directory: build

‎.readthedocs.yaml

-1
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,6 @@ build:
1515
- (git --no-pager log --pretty="tformat:%s -- %b" -1 | paste -s -d " " | grep -viqP "skip ci|ci skip") || exit 183
1616
pre_build:
1717
- ./doc/rtd/pre_build.sh
18-
- cd doc && make doxygen
1918

2019
apt_packages:
2120
- ant

‎doc/CMakeLists.txt

+145-53
Original file line numberDiff line numberDiff line change
@@ -2,23 +2,19 @@
22

33
find_package(Doxygen)
44
find_program(SPHINX_BUILD sphinx-build)
5-
find_program(MAKE_EXECUTABLE make)
65

7-
if (UNIX
8-
AND (NOT "${CMAKE_BINARY_DIR}" STREQUAL "${CMAKE_SOURCE_DIR}")
6+
7+
if ((NOT "${CMAKE_BINARY_DIR}" STREQUAL "${CMAKE_SOURCE_DIR}")
98
AND DOXYGEN_FOUND
10-
AND SPHINX_BUILD
11-
AND MAKE_EXECUTABLE)
9+
AND SPHINX_BUILD)
1210
set(BUILD_DOCS_DEFAULT ON)
1311
else()
1412
set(BUILD_DOCS_DEFAULT OFF)
1513
endif()
16-
option(BUILD_DOCS "Set to ON to define documentation targets: 'html', 'latexpdf', 'man', 'doxygen', 'doxygen_check_warnings', 'spelling', 'clean_doc'" ${BUILD_DOCS_DEFAULT})
14+
15+
option(BUILD_DOCS "Set to ON to define documentation targets: 'html', 'latexpdf', 'man', 'doxygen_xml', 'doxygen_html' " ${BUILD_DOCS_DEFAULT})
1716

1817
if (BUILD_DOCS)
19-
if (NOT UNIX)
20-
message(FATAL_ERROR "BUILD_DOCS=ON requires a UNIX environment")
21-
endif()
2218
if ("${CMAKE_BINARY_DIR}" STREQUAL "${CMAKE_SOURCE_DIR}")
2319
message(FATAL_ERROR "BUILD_DOCS=ON not compatible of in-source builds (CMAKE_SOURCE_DIR=CMAKE_BINARY_DIR)")
2420
endif()
@@ -28,49 +24,145 @@ if (BUILD_DOCS)
2824
if (NOT SPHINX_BUILD)
2925
message(FATAL_ERROR "BUILD_DOCS=ON requires sphinx-build")
3026
endif()
31-
if (NOT MAKE_EXECUTABLE)
32-
message(FATAL_ERROR "BUILD_DOCS=ON requires 'make' executable")
33-
endif()
3427

35-
set(DOC_BUILDDIR "${CMAKE_CURRENT_BINARY_DIR}/build")
36-
37-
add_custom_target(
38-
doxygen
39-
COMMAND ${MAKE_EXECUTABLE} doxygen BUILDDIR=${DOC_BUILDDIR}
40-
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})
41-
42-
add_custom_target(
43-
doxygen_check_warnings
44-
COMMAND ${MAKE_EXECUTABLE} doxygen_check_warnings BUILDDIR=${DOC_BUILDDIR}
45-
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})
46-
47-
add_custom_target(
48-
html
49-
COMMAND ${MAKE_EXECUTABLE} html BUILDDIR=${DOC_BUILDDIR}
50-
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})
51-
52-
add_custom_target(
53-
latexpdf
54-
COMMAND ${MAKE_EXECUTABLE} latexpdf BUILDDIR=${DOC_BUILDDIR}
55-
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})
56-
57-
add_custom_target(
58-
man
59-
COMMAND ${MAKE_EXECUTABLE} man BUILDDIR=${DOC_BUILDDIR}
60-
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})
61-
62-
add_custom_target(
63-
spelling
64-
COMMAND ${MAKE_EXECUTABLE} spelling BUILDDIR=${DOC_BUILDDIR}
65-
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})
66-
67-
add_custom_target(
68-
clean_doc
69-
COMMAND ${MAKE_EXECUTABLE} clean BUILDDIR=${DOC_BUILDDIR}
70-
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})
71-
72-
set_property(
73-
TARGET clean_doc
74-
APPEND
75-
PROPERTY ADDITIONAL_CLEAN_FILES ${DOC_BUILDDIR})
28+
####################################################################################################
29+
# Sphinx configuration
30+
####################################################################################################
31+
32+
# Determine environment variables so that Sphinx can load the gdal Python module without installing it.
33+
include(GdalSetRuntimeEnv)
34+
gdal_set_runtime_env(PYTHON_RUN_ENV)
35+
36+
set(SPHINX_BUILD_DIR ${CMAKE_CURRENT_BINARY_DIR}/build)
37+
set(SPHINX_BUILD_OPTS "--jobs=auto" "--fail-on-warning" "--show-traceback")
38+
file(MAKE_DIRECTORY ${SPHINX_BUILD_DIR})
39+
file(MAKE_DIRECTORY ${SPHINX_BUILD_DIR}/html_extra)
40+
41+
file(GLOB_RECURSE SPHINX_SOURCE_FILES CONFIGURE_DEPENDS
42+
${CMAKE_CURRENT_SOURCE_DIR}/source/**/*.rst
43+
${CMAKE_CURRENT_SOURCE_DIR}/source/**/*.py)
44+
45+
####################################################################################################
46+
# Doxygen XML and HTML outputs
47+
####################################################################################################
48+
49+
# Create a dependency between source files and Doxygen
50+
# This is more aggressive than needed, because we only build Doxygen for a subset of the source tree
51+
file(GLOB_RECURSE DOXYGEN_SOURCE_FILES CONFIGURE_DEPENDS ${CMAKE_SOURCE_DIR}/**/*.cpp)
52+
53+
# Use configure_file to copy the Doxygen file into our build directory.
54+
# This causes CMake to re-run if the contents of the Doxyfile change.
55+
configure_file(${CMAKE_SOURCE_DIR}/Doxyfile ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile_base)
56+
57+
# Read the contents of the copied Doxyfile, so that we can write modified versions
58+
# for XML and HTML outputs
59+
file(READ ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile_base DOXYFILE_CONTENTS)
60+
61+
# Doxygen XML outputs
62+
# TODO <ndash> replacement?
63+
string(JOIN "\n" DOXYFILE_XML_CONTENTS
64+
${DOXYFILE_CONTENTS}
65+
"FAIL_ON_WARNINGS=YES"
66+
"WARN_AS_ERROR=FAIL_ON_WARNINGS_PRINT"
67+
"GENERATE_HTML=NO"
68+
"GENERATE_XML=YES"
69+
"XML_OUTPUT=${SPHINX_BUILD_DIR}/xml"
70+
"XML_PROGRAMLISTING=NO"
71+
"PREDEFINED+=DOXYGEN_XML"
72+
)
73+
file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile_xml ${DOXYFILE_XML_CONTENTS})
74+
add_custom_command(
75+
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/doxygen_xml.stamp
76+
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile_xml ${DOXYGEN_SOURCE_FILES}
77+
WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
78+
COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile_xml
79+
COMMAND ${CMAKE_COMMAND} -E touch ${CMAKE_CURRENT_BINARY_DIR}/doxygen_xml.stamp
80+
)
81+
82+
add_custom_target(doxygen_xml
83+
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/doxygen_xml.stamp
84+
)
85+
86+
# Doxygen HTML outputs
87+
string(JOIN "\n" DOXYFILE_HTML_CONTENTS
88+
"${DOXYFILE_CONTENTS}"
89+
"FAIL_ON_WARNINGS=YES"
90+
"WARN_AS_ERROR=FAIL_ON_WARNINGS_PRINT"
91+
"HTML_OUTPUT=${SPHINX_BUILD_DIR}/html_extra/doxygen"
92+
"INLINE_INHERITED_MEMB=YES"
93+
)
94+
file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile_html ${DOXYFILE_HTML_CONTENTS})
95+
add_custom_command(
96+
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/doxygen_html.stamp
97+
WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
98+
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile_html ${DOXYGEN_SOURCE_FILES}
99+
COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile_html
100+
COMMAND ${CMAKE_COMMAND} -E touch ${CMAKE_CURRENT_BINARY_DIR}/doxygen_html.stamp
101+
)
102+
add_custom_target(doxygen_html
103+
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/doxygen_html.stamp
104+
)
105+
106+
####################################################################################################
107+
# Sphinx outputs
108+
####################################################################################################
109+
110+
# Sphinx HTML documentation
111+
add_custom_command(
112+
OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/html.stamp"
113+
DEPENDS doxygen_xml python_binding
114+
${SPHINX_SOURCE_FILES}
115+
COMMAND ${CMAKE_COMMAND} -E env ${PYTHON_RUN_ENV} BUILDDIR=${SPHINX_BUILD_DIR}
116+
${SPHINX_BUILD} -M html
117+
${CMAKE_CURRENT_SOURCE_DIR}/source
118+
${CMAKE_CURRENT_BINARY_DIR}/build
119+
${SPHINX_BUILD_OPTS}
120+
COMMAND ${CMAKE_COMMAND} -E touch "${CMAKE_CURRENT_BINARY_DIR}/html.stamp"
121+
)
122+
123+
add_custom_target(html
124+
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/html.stamp
125+
)
126+
127+
# Sphinx PDF documentation
128+
add_custom_command(
129+
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/build/gdal.pdf
130+
DEPENDS ${SPHINX_SOURCE_FILES}
131+
COMMAND ${CMAKE_COMMAND} -E env BUILDDIR=${SPHINX_BUILD_DIR}
132+
${SPHINX_BUILD} -M latexpdf
133+
${CMAKE_CURRENT_SOURCE_DIR}/source
134+
${CMAKE_CURRENT_BINARY_DIR}/build
135+
${SPHINX_BUILD_OPTS}
136+
)
137+
138+
add_custom_target(latexpdf DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/build/gdal.pdf)
139+
140+
# Sphinx manpage documentation
141+
add_custom_command(
142+
OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/man.stamp"
143+
DEPENDS ${SPHINX_SOURCE_FILES}
144+
COMMAND ${CMAKE_COMMAND} -E env BUILDDIR=${SPHINX_BUILD_DIR}
145+
${SPHINX_BUILD} -M man
146+
${CMAKE_CURRENT_SOURCE_DIR}/source
147+
${CMAKE_CURRENT_BINARY_DIR}/build
148+
${SPHINX_BUILD_OPTS}
149+
COMMAND ${CMAKE_COMMAND} -E touch "${CMAKE_CURRENT_BINARY_DIR}/man.stamp"
150+
)
151+
152+
add_custom_target(man DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/man.stamp)
153+
154+
####################################################################################################
155+
# Documentation tests
156+
####################################################################################################
157+
158+
# Spell check
159+
add_test(NAME doc-spelling
160+
COMMAND ${CMAKE_COMMAND} -E env ${PYTHON_RUN_ENV} BUILDDIR=${SPHINX_BUILD_DIR}
161+
${SPHINX_BUILD} -b spelling
162+
${CMAKE_CURRENT_SOURCE_DIR}/source
163+
${CMAKE_CURRENT_BINARY_DIR}/build
164+
${SPHINX_BUILD_OPTS}
165+
-D html_extra_path=extra_path
166+
)
167+
76168
endif ()

0 commit comments

Comments
 (0)