trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bner...@apache.org
Subject [trafficserver] branch 8.1.x updated: 8.1.x doc tweaks to support Sphinx 3.x (#7984)
Date Fri, 25 Jun 2021 22:40:32 GMT
This is an automated email from the ASF dual-hosted git repository.

bneradt pushed a commit to branch 8.1.x
in repository https://gitbox.apache.org/repos/asf/trafficserver.git


The following commit(s) were added to refs/heads/8.1.x by this push:
     new e505fed  8.1.x doc tweaks to support Sphinx 3.x (#7984)
e505fed is described below

commit e505fede4beea54c0c2bea2b70dc795c106505ad
Author: Brian Neradt <brian.neradt@gmail.com>
AuthorDate: Fri Jun 25 17:40:25 2021 -0500

    8.1.x doc tweaks to support Sphinx 3.x (#7984)
    
    * This adds a Pipfile for the docs Python package requirements and
      configures it to use Sphinx 3.x.
    * Shinx 3.x also requested us to run 2to3 on conf.py in anticipation of
      Sphinx 4.x
    * A couple tweaks were needed to the traffic-server.py for a change to
      the Sphinx  interface (`l_` no longer exists).
---
 doc/Pipfile               | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 doc/conf.py               | 32 ++++++++++++++++----------------
 doc/ext/traffic-server.py |  6 +++---
 3 files changed, 66 insertions(+), 19 deletions(-)

diff --git a/doc/Pipfile b/doc/Pipfile
new file mode 100644
index 0000000..42a9f5a
--- /dev/null
+++ b/doc/Pipfile
@@ -0,0 +1,47 @@
+#  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.
+
+[[source]]
+name = "pypi"
+url = "https://pypi.org/simple"
+verify_ssl = true
+
+[dev-packages]
+
+[packages]
+
+# The latest 4.x sphinx release, currently 4.0.2, fails `make html`.  For
+# details, see: https://github.com/apache/trafficserver/issues/7938
+#
+# The 3.x releases build fine, however. So we currently pin to that.
+#
+# Once that issue, either with sphinx or our docs, is resolved, then we should
+# unpin sphinx by setting the following to "*".
+sphinx = "==3.*"
+
+sphinx-rtd-theme = "*"
+sphinxcontrib-plantuml = "*"
+# i18n
+sphinx-intl = "*"
+
+# For parsing Doxygen XML output, to add links from an API description
+# to the source code for that object
+lxml = "*"
+
+polib = ">=1.0.3"
+
+[requires]
+python_version = "3"
diff --git a/doc/conf.py b/doc/conf.py
index 0a8449d..54c2805 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -57,7 +57,7 @@ extensions = [
 ]
 
 # Contains values that are dependent on configure.ac.
-execfile('ext/local-config.py')
+exec(compile(open('ext/local-config.py', "rb").read(), 'ext/local-config.py', 'exec'))
 
 if version_info >= (1, 4):
     extensions.append('sphinx.ext.imgmath')
@@ -83,8 +83,8 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-project = u'Apache Traffic Server'
-copyright = u'{}, dev@trafficserver.apache.org'.format(date.today().year)
+project = 'Apache Traffic Server'
+copyright = '{}, dev@trafficserver.apache.org'.format(date.today().year)
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -114,7 +114,7 @@ gettext_compact = False
 # Generate .mo files just in time
 if os.environ.get('READTHEDOCS') == 'True':
     import polib
-    print "Generating .mo files",
+    print("Generating .mo files", end=' ')
     for locale_dir in locale_dirs:
         for path, dummy, filenames in os.walk(locale_dir):
             for filename in filenames:
@@ -124,7 +124,7 @@ if os.environ.get('READTHEDOCS') == 'True':
                     mo_file = base + ".mo"
                     po = polib.pofile(po_file)
                     po.save_as_mofile(fpath=mo_file)
-    print "done"
+    print("done")
 else:
     # On RedHat-based distributions, install the python-sphinx_rtd_theme package
     # to get an end result tht looks more like readthedoc.org.
@@ -203,17 +203,17 @@ class Inliner(states.Inliner):
         # Copied from states.Inliner.init_customizations().
         # In Docutils 0.13 these are locals.
         if not hasattr(self, 'start_string_prefix'):
-            self.start_string_prefix = (u'(^|(?<=\\s|[%s%s]))' %
+            self.start_string_prefix = ('(^|(?<=\\s|[%s%s]))' %
                                         (punctuation_chars.openers,
                                          punctuation_chars.delimiters))
         if not hasattr(self, 'end_string_suffix'):
-            self.end_string_suffix = (u'($|(?=\\s|[\x00%s%s%s]))' %
+            self.end_string_suffix = ('($|(?=\\s|[\x00%s%s%s]))' %
                                       (punctuation_chars.closing_delimiters,
                                        punctuation_chars.delimiters,
                                        punctuation_chars.closers))
 
         issue = re.compile(
-            ur'''
+            r'''
       {start_string_prefix}
       TS-\d+
       {end_string_suffix}'''.format(
@@ -352,8 +352,8 @@ elif tags.has('latex_paper'):
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-    ('index', 'ApacheTrafficServer.tex', u'Apache Traffic Server Documentation',
-     u'dev@trafficserver.apache.org', 'manual'),
+    ('index', 'ApacheTrafficServer.tex', 'Apache Traffic Server Documentation',
+     'dev@trafficserver.apache.org', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -445,8 +445,8 @@ manpage.ManualPageTranslator = ManualPageTranslator
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    ('index', 'ApacheTrafficServer', u'Apache Traffic Server Documentation',
-     u'dev@trafficserver.apache.org', 'ApacheTrafficServer', 'One line description of project.',
+    ('index', 'ApacheTrafficServer', 'Apache Traffic Server Documentation',
+     'dev@trafficserver.apache.org', 'ApacheTrafficServer', 'One line description of project.',
      'Miscellaneous'),
 ]
 
@@ -462,10 +462,10 @@ texinfo_documents = [
 # -- Options for Epub output ---------------------------------------------------
 
 # Bibliographic Dublin Core info.
-epub_title = u'Apache Traffic Server'
-epub_author = u'dev@trafficserver.apache.org'
-epub_publisher = u'dev@trafficserver.apache.org'
-epub_copyright = u'2013, dev@trafficserver.apache.org'
+epub_title = 'Apache Traffic Server'
+epub_author = 'dev@trafficserver.apache.org'
+epub_publisher = 'dev@trafficserver.apache.org'
+epub_copyright = '2013, dev@trafficserver.apache.org'
 
 # The language of the text. It defaults to the language option
 # or en if the language is not set.
diff --git a/doc/ext/traffic-server.py b/doc/ext/traffic-server.py
index 24d9ef6..74a4f7f 100644
--- a/doc/ext/traffic-server.py
+++ b/doc/ext/traffic-server.py
@@ -31,7 +31,7 @@ from docutils.parsers import rst
 from docutils.parsers.rst import directives
 from sphinx.domains import Domain, ObjType, std
 from sphinx.roles import XRefRole
-from sphinx.locale import l_, _
+from sphinx.locale import _
 import sphinx
 
 import subprocess
@@ -301,8 +301,8 @@ class TrafficServerDomain(Domain):
     data_version = 2
 
     object_types = {
-        'cv': ObjType(l_('configuration variable'), 'cv'),
-        'stat': ObjType(l_('statistic'), 'stat')
+        'cv': ObjType(_('configuration variable'), 'cv'),
+        'stat': ObjType(_('statistic'), 'stat')
     }
 
     directives = {

Mime
View raw message