trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From da...@apache.org
Subject [trafficserver] branch master updated: Enforce sphinx>=1.7.5 when building docs
Date Tue, 10 Jul 2018 18:10:40 GMT
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 <derekd@oath.com>
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.


Mime
View raw message