Run Sphinx generation in Python 3.

Issue web-platform-tests#23081

This CL made the following changes:
[1] Upgrading Sphinx version to 3.3.1 to support python 3.5+
[2] Fixing bugs invoked during Py3 run.
    a) Replace reference of "index" in checklist.md with relative path for
       index.md. This is due to "more than one target found for cross-reference"
       error thrown by Sphinx referring to it. It's a known issue in
       sphinx (sphinx-doc/sphinx#2549)
    b) Fix Sphinx in third_party/pywebsocket3. A PR has been sent at
       GoogleChromeLabs/pywebsocket3#16

Note: Command to run with Python3 is: wpt --py3 build-docs

Author: ziransun

docs/conf.py

@@ -78,6 +78,9 @@
     ('py:exc', 'BadOperationException'),
     ('py:exc', 'Exception'),
     ('py:exc', 'ValueError'),
+    ('py:class', 'integer -- return number of occurrences of value'),
+    ('py:class', 'integer -- return first index of value.'),
+    ('py:class', 'http.client.HTTPMessage')
 ]
 
 # The language for content autogenerated by Sphinx. Refer to documentation
@@ -211,5 +214,5 @@ def setup(app):
 # A list of files that should not be packed into the epub file.
 epub_exclude_files = ['search.html']
 
-intersphinx_mapping = {'python': ('https://docs.python.org/2/', None),
+intersphinx_mapping = {'python': ('https://docs.python.org/3/', None),
                        'mozilla': ('https://firefox-source-docs.mozilla.org/', None)}

docs/requirements.txt

@@ -1,4 +1,4 @@
 recommonmark==0.6.0
 # pin this to the last Py2 release
-Sphinx==1.8.5  # pyup: <2.0
+Sphinx==3.3.1  # pyup: <2.0
 sphinx-argparse==0.2.5

docs/reviewing-tests/checklist.md

@@ -5,7 +5,7 @@ tests; in case of any contradiction with requirements stated elsewhere in the
 documentation it should be ignored
 (please [file a bug](https://github.com/web-platform-tests/wpt/issues/new)!).
 
-As noted on the [reviewing tests](index) page, nits need not block PRs
+As noted on the [reviewing tests](./index.md) page, nits need not block PRs
 from landing.
 
 

docs/wpt_lint_rules.py

@@ -3,6 +3,7 @@
 from recommonmark.parser import CommonMarkParser
 import importlib
 import textwrap
+from six import iteritems
 
 class WPTLintRules(Directive):
     """A docutils directive to generate documentation for the
@@ -31,7 +32,7 @@ def _get_rules(self):
                 """wpt-lint-rules: unable to resolve the module at "{}".""".format(self.module_specifier)
             )
 
-        for binding_name, value in module.__dict__.iteritems():
+        for binding_name, value in iteritems(module.__dict__):
             if hasattr(value, "__abstractmethods__") and len(value.__abstractmethods__):
                 continue
 

tools/third_party/pywebsocket3/mod_pywebsocket/stream.py

@@ -875,7 +875,7 @@ def close_connection(self,
             wait_response: True when caller want to wait the response.
         Raises:
             BadOperationException: when reason is specified with code None
-            or reason is not an instance of both str and unicode.
+                or reason is not an instance of both str and unicode.
         """
 
         if self._request.server_terminated: