This is an automated email from the ASF dual-hosted git repository.
dagit pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficserver.git
The following commit(s) were added to refs/heads/master by this push:
new 5646efc Enforce sphinx>=1.7.5 when building docs
5646efc is described below
commit 5646efcf05d3ac2b165c8f07925d8964b8dbc56f
Author: Derek Dagit <[email protected]>
AuthorDate: Mon Jul 9 11:47:15 2018 -0500
Enforce sphinx>=1.7.5 when building docs
If the option `--enable-docs` is used with configure, then we enforce the
presence of sphinx (and its support packages) in the same
way that we currently enforce the presence of java.
This is needed since certain C++ method declarations can be parsed
successfully only by newer versions of sphinx with certain bug
fixes.
The sphinx package installs a script executable sphinx-build that is called
directly when building the documentation. This script
has an interpreter directive following the `#!` first line that selects a
specific python executable to interpret the script.
Systems that have multiple python versions installed may have sphinx
installed on one other than the first python found on the path,
or they may have conflicting versions of sphinx installed with different
versions of python. Therefore an accurate check on sphinx
needs to use the matching interpreter.
---
configure.ac | 18 ++++++++++--------
doc/checkvers.py | 12 +++++++-----
doc/checkvers.sh | 40 ++++++++++++++++++++++++++++++++++++++++
doc/conf.py | 12 +-----------
4 files changed, 58 insertions(+), 24 deletions(-)
diff --git a/configure.ac b/configure.ac
index 201c33d..a53428d 100644
--- a/configure.ac
+++ b/configure.ac
@@ -308,6 +308,16 @@ AC_ARG_ENABLE([docs],
enable_doc_build=no
AC_ERROR([Doc building disabled, java required but not found])
])
+ AC_ARG_VAR(SPHINXBUILD, [the sphinx-build documentation generator])
+ AC_PATH_PROG([SPHINXBUILD], [sphinx-build], [])
+ AS_IF(["$srcdir/doc/checkvers.sh" "$SPHINXBUILD"
"$srcdir/doc/checkvers.py"],
+ [
+ sphinx_version_check=yes
+ ],[
+ sphinx_version_check=no
+ enable_doc_build=no
+ AC_ERROR([Doc building disabled, check sphinx installation])
+ ])
],
[enable_doc_build=no]
)
@@ -716,21 +726,13 @@ AM_PATH_PYTHON([2.4], [
TS_MAN3_MANPAGES=`cd $srcdir/doc && $PYTHON manpages.py --section=3 | $AWK
'{print "$(BUILDDIR)/man/" $0 }' | tr '\n' ' '`
TS_MAN5_MANPAGES=`cd $srcdir/doc && $PYTHON manpages.py --section=5 | $AWK
'{print "$(BUILDDIR)/man/" $0 }' | tr '\n' ' '`
TS_MAN8_MANPAGES=`cd $srcdir/doc && $PYTHON manpages.py --section=8 | $AWK
'{print "$(BUILDDIR)/man/" $0 }' | tr '\n' ' '`
-
- # If we have python, check if the Sphinx version looks OK.
- AS_IF(["$PYTHON" "$srcdir/doc/checkvers.py" --check-version], [
- sphinx_version_check=yes
- ])
-
], [
dnl action-if-not-found
:
])
AC_ARG_VAR(RPATH, [path to be added to rpath])
-AC_ARG_VAR(SPHINXBUILD, [the sphinx-build documentation generator])
AC_ARG_VAR(SPHINXOPTS, [additional sphinx-build options])
-AC_CHECK_PROG([SPHINXBUILD], [sphinx-build], [sphinx-build], [false])
AC_ARG_VAR([CLANG_TIDY], [clang-tidy command])
diff --git a/doc/checkvers.py b/doc/checkvers.py
index 70b4eab..398680e 100644
--- a/doc/checkvers.py
+++ b/doc/checkvers.py
@@ -26,10 +26,12 @@ if __name__ == '__main__':
(options, args) = parser.parse_args()
- # Check whether we have a recent version of sphinx. EPEL and CentOS are
completely crazy and I don't understand their
- # packaging at all. The test below works on Ubuntu and places where sphinx
is installed sanely AFAICT.
+ # Check whether we have the required version of sphinx.
if options.checkvers:
- print('checking for sphinx version >= 1.5.1... '),
+ min_sphinx_version_info = (1,7,5)
+ min_sphinx_version = '.'.join([str(x) for x in
min_sphinx_version_info])
+
+ print('checking for sphinx version >= {0}...
'.format(min_sphinx_version))
# Need at least 1.5.1 to use svg
# version >= 1.2 guarantees sphinx.version_info is available.
try:
@@ -42,8 +44,8 @@ if __name__ == '__main__':
print('Found Sphinx version (old)
{0}'.format(sphinx.__version__))
sphinx.version_info = version.split('.')
- if sphinx.version_info < (1, 5, 1):
- print('sphinx version is older than 1.5.1')
+ if sphinx.version_info < min_sphinx_version_info:
+ print('sphinx version is older than
{0}'.format(min_sphinx_version))
sys.exit(1)
except Exception as e:
diff --git a/doc/checkvers.sh b/doc/checkvers.sh
new file mode 100755
index 0000000..2e95771
--- /dev/null
+++ b/doc/checkvers.sh
@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+if [[ ! -r "$1" ]]
+then
+ echo "Expecting sphinx-build executable at '$1' but could not read it" >&2
+ exit 1
+fi
+
+# We must grab the interpreter directive from the sphinx-build script to
discover which python installation should be used to check
+# the version.
+sphinx_build_PYTHON="$(head -n 1 "$1" | sed 's;^#! *;;')"
+
+if [[ ! -x "$sphinx_build_PYTHON" ]]
+then
+ echo "sphinx-build found at '$1' needs missing '$sphinx_build_PYTHON'" >&2
+ return 1
+fi
+
+if [[ ! -r "$2" ]]
+then
+ echo "Expecting sphinx version check script at '$1' but could not read it"
>&2
+ exit 1
+fi
+
+"$sphinx_build_PYTHON" "$2" --check-version
diff --git a/doc/conf.py b/doc/conf.py
index 2ba2050..1f09e42 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -43,9 +43,6 @@ from manpages import man_pages
# -- General configuration
-----------------------------------------------------
-# If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
-
# Add any Sphinx extension module names here, as strings. They can be
extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [
@@ -170,14 +167,7 @@ pygments_style = 'sphinx'
#modindex_common_prefix = []
nitpicky = True
-nitpick_ignore = [ ('cpp:typeOrConcept', 'std')
- , ('cpp:typeOrConcept', 'std::shared_ptr')
- , ('cpp:typeOrConcept', 'std::ostream')
- , ('cpp:typeOrConcept', 'std::string')
- , ('cpp:typeOrConcept', 'std::string_view')
- , ('cpp:typeOrConcept', 'std::tuple')
- , ('cpp:typeOrConcept', 'V') # template arguments which
should be matched but aren't.
- , ('cpp:typeOrConcept', 'Args')
+nitpick_ignore = [
]
# Autolink issue references.
