/
oac_setup_sphinx.m4
179 lines (163 loc) · 7.77 KB
/
oac_setup_sphinx.m4
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
dnl -*- autoconf -*-
dnl
dnl Copyright (c) 2020-2022 Cisco Systems, Inc. All rights reserved.
dnl Copyright (c) 2024 Jeffrey M. Squyres. All rights reserved.
dnl
dnl $COPYRIGHT$
dnl
dnl Additional copyrights may follow
dnl
dnl $HEADER$
dnl
dnl Setup Sphinx for building HTML docs and man pages
dnl
dnl 1 -> sanity file to check if pre-built docs are already available
dnl You probably want to pass something like
dnl "$srcdir/docs/_build/man/foo.1"
dnl
dnl 2 -> (OPTIONAL) URL to display in AC_MSG_WARN when docs will not be installed
dnl If $2 is empty, nothing will be displayed.
dnl Note: if $2 contains a #, be sure to double quote it
dnl (e.g., [[https://example.com/foo.html#some-anchor]])
dnl
dnl 3 -> (OPTIONAL) Filename of requirements.txt-like file containing
dnl the required Pip modules (to be displayed if rendering a
dnl simple RST project fails).
dnl
dnl This macro requires that OAC_PUSH_PREFIX was previously called.
dnl The pushed prefix may be used if this macro chooses to set {OAC
dnl prefix}_MAKEDIST_DISABLE. If set, it is a message indicating why
dnl "make dist" should be disabled, suitable for emitting via
dnl AC_MSG_WARN.
AC_DEFUN([OAC_SETUP_SPHINX],[
OAC_ASSERT_PREFIX_DEFINED([$0])
OAC_VAR_SCOPE_PUSH([oac_summary_msg oac_sphinx_result oac_install_docs oac_sphinx_target_version oac_sphinx_found_version])
# This option is probably only helpful to developers: have
# configure fail if Sphinx is not found (i.e., if you don't have
# the ability to use Sphinx to build the HTML docs and man pages).
AC_ARG_ENABLE([sphinx],
[AS_HELP_STRING([--enable-sphinx],
[Force configure to fail if Sphinx is not found (Sphinx is used to build the HTML docs and man pages). This option is likely only useful for developers; end users who are building from distribution tarballs do ***not*** need to have Sphinx installed])])
# Quick check to see if we have already-built docs (e.g., if we're
# in a tarball vs. a fresh git clone).
AC_MSG_CHECKING([if pre-built docs are available])
AS_IF([test -f "$1"],
[oac_install_docs=1
AC_MSG_RESULT([yes])],
[oac_install_docs=0
AC_MSG_RESULT([no])])
# To generate HTML docs + man pages, we need Sphinx. If we have
# Sphinx, then we're able to both build and install the docs
# (potentially overriding oac_install_docs from what it was set
# above).
AC_PATH_PROG([SPHINX_BUILD], [sphinx-build], [])
# If the user requested to disable sphinx, then pretend we didn't
# find it.
AS_IF([test "$enable_sphinx" = "no"],
[SPHINX_BUILD=])
# If we found Sphinx, check to ensure that it's a recent enough
# version.
AS_IF([test -n "$SPHINX_BUILD"],
[[oac_sphinx_target_version=`sed -n -e 's/sphinx[><=]*\([0-9\.]\)/\1/p' $srcdir/docs/requirements.txt`]
# Some older versions of Sphinx (e.g., Sphinx v1.1.3 in
# RHEL 7):
#
# - Don't support "--version".
# - But do emit the version number as part of the general
# CLI help when they don't recognize the --version CLI
# option.
#
# In that case, we only want the first line, and we want to
# strip off the leading "v" from the version number.
#
# In the case where --version *is* recognized, all the
# additional processing is harmless and we still end up
# with the Sphinx version number.
oac_sphinx_found_version=`$SPHINX_BUILD --version 2>&1 | head -n 1 | cut -d\ -f2 | sed -e 's/^v//'`
AC_MSG_CHECKING([if Sphinx version is high enough ($oac_sphinx_found_version >= $oac_sphinx_target_version)])
AS_VERSION_COMPARE([$oac_sphinx_found_version],
[$oac_sphinx_target_version],
[oac_sphinx_result=lesser],
[oac_sphinx_result=equal],
[oac_sphinx_result=greater])
AS_IF([test "$oac_sphinx_result" = "lesser"],
[SPHINX_BUILD=
AC_MSG_RESULT([no])],
[ # If we're building, we're also installing, regardless of
# whether we found pre-build docs or not (above).
oac_install_docs=1
AC_MSG_RESULT([yes])])
])
# If we found Sphinx, check to ensure that we have all the things
# required to build Open MPI/PRRTE/OpenPMIx-like documentation
# (e.g., any required pip modules). If we can't render a sample
# OMPI-like doc, we're not going to automatically install any
# missing pip modules; we'll just mark Sphinx as being
# unavailable.
AS_IF([test -n "$SPHINX_BUILD"],
[AC_MSG_CHECKING([for required Sphinx modules])
oac_startdir=`pwd`
oac_tmpdir=conftmp.$$
rm -rf $oac_tmpdir
mkdir $oac_tmpdir
cd $oac_tmpdir
cat > conf.py <<EOF
# Minimum config that we need for Open MPI/PRRTE/OpenPMIx-like docs
project = 'Testing'
copyright = 'Testing'
author = 'Testing'
import sphinx_rtd_theme
# Note the extra quoting needed for square brackets because this is m4
extensions = [[ 'recommonmark', 'sphinx_rtd_theme', 'sphinx.ext.extlinks' ]]
html_theme = 'sphinx_rtd_theme'
EOF
echo "Hello world" > index.rst
# Try to render this trivial RST project as both HTML and
# man pages and see if it works.
oac_happy=0
OAC_LOG_COMMAND([$SPHINX_BUILD -M html . build-html],
[OAC_LOG_COMMAND([$SPHINX_BUILD -M man . build-man],
[oac_happy=1])])
AS_IF([test $oac_happy -eq 1],
[AC_MSG_RESULT([found])],
[SPHINX_BUILD=
AC_MSG_RESULT([not found])])
cd $oac_startdir
rm -rf $oac_tmpdir
])
AS_IF([test -z "$SPHINX_BUILD"],
_oac_program_prefix[_MAKEDIST_DISABLE="$]_oac_program_prefix[_MAKEDIST_DISABLE Sphinx/Documentation"
AC_MSG_NOTICE([Could not find a suitable sphinx-build on your system.])
AS_IF([test -n "$3"],
[AC_MSG_NOTICE([If you want to build the documentation, ensure that the])
AC_MSG_NOTICE([Python modules in $3])
AC_MSG_NOTICE([are available.])
])
AC_MSG_NOTICE([You will not be able to build a distribution tarball.])
])
AS_IF([test $oac_install_docs -eq 0],
[AC_MSG_WARN([*** You will not have documentation installed.])
AS_IF([test -n "$2"],
[AC_MSG_WARN([*** See the following URL for more information:])
AC_MSG_WARN([*** $2])])
])
# If --enable-sphinx was specified and we did not find Sphinx,
# abort. This is likely only useful to prevent "oops!" moments
# from developers.
AS_IF([test -z "$SPHINX_BUILD" && test "$enable_sphinx" = "yes"],
[AC_MSG_WARN([A suitable Sphinx was not found, but --enable-sphinx was specified])
AC_MSG_ERROR([Cannot continue])])
# Construct a summary message. Due SUMMARY_ADD's implementation,
# do *not* include a comma.
AS_IF([test -n "$SPHINX_BUILD"],
[ # If we found Sphinx, we always both build and install.
oac_summary_msg="building and installing"],
[AS_IF([test $oac_install_docs -eq 1],
[oac_summary_msg="installing packaged docs"],
[oac_summary_msg="no documentation available"])])
OAC_SUMMARY_ADD([Miscellaneous], [HTML docs and man pages],
[$oac_summary_msg])
AM_CONDITIONAL(_oac_program_prefix[_BUILD_DOCS], [test -n "$SPHINX_BUILD"])
AM_CONDITIONAL(_oac_program_prefix[_INSTALL_DOCS], [test $oac_install_docs -eq 1])
OAC_VAR_SCOPE_POP
])