trafficserver-commits mailing list archives

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

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


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

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

    7.1.x doc tweaks to support Sphinx 3.x (#7985)
    
    * 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
    * Addressed conf.py processing error concerning
      sphinx.domains.c.CObject.stopwords via nitpick_ignore.
    * 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               | 46 ++++++++++++++++++++++++++++++----------------
 doc/ext/traffic-server.py | 10 +++-------
 3 files changed, 80 insertions(+), 23 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 1b4e037..6586929 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -81,8 +81,8 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-project = u'Apache Traffic Server'
-copyright = u'2016, dev@trafficserver.apache.org'
+project = 'Apache Traffic Server'
+copyright = '2016, dev@trafficserver.apache.org'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -112,7 +112,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:
@@ -122,7 +122,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.
@@ -164,7 +164,21 @@ pygments_style = 'default'
 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
 
-nitpicky = 1
+nitpicky = True
+nitpick_ignore = [('c:identifier', 'int64_t'),
+                  ('c:identifier', 'uint64_t'),
+                  ('c:identifier', 'uint8_t'),
+                  ('c:identifier', 'int32_t'),
+                  ('c:identifier', 'size_t'),
+                  ('c:identifier', 'ssize_t'),
+                  ('c:identifier', 'sockaddr'),
+                  ('c:identifier', 'time_t'),
+                  ('cpp:identifier', 'T'),  # template arg
+                  ('cpp:identifier', 'F'),  # template arg
+                  ('cpp:identifier', 'Args'),  # variadic template arg
+                  ('cpp:identifier', 'Rest'),  # variadic template arg
+                  ]
+
 
 # Autolink issue references.
 # See Customizing the Parser in the docutils.parsers.rst module.
@@ -193,17 +207,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(
@@ -337,8 +351,8 @@ latex_elements = {
 # 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
@@ -430,8 +444,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'),
 ]
 
@@ -447,10 +461,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 6f24987..11a34c2 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 = {
@@ -460,8 +460,4 @@ def setup(app):
     # this lets us do :ts:git:`<file_path>` and link to the file on github
     app.add_role_to_domain('ts', 'git', make_github_link)
 
-    # Types that we want the C domain to consider built in
-    for word in EXTERNAL_TYPES:
-        sphinx.domains.c.CObject.stopwords.add(word)
-
     app.connect('missing-reference', xref_cleanup)

Mime
View raw message