Run Sphinx generation in Python 3. (#26574)

Fixes #23081

This CL made the following changes:
[1] Upgrading Sphinx version to 2.4.4 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

Co-authored-by: Robert Ma <[email protected]>

docs/conf.py

@@ -78,6 +78,7 @@
     ('py:exc', 'BadOperationException'),
     ('py:exc', 'Exception'),
     ('py:exc', 'ValueError'),
+    ('py:class', 'http.client.HTTPMessage')
 ]
 
 # The language for content autogenerated by Sphinx. Refer to documentation
@@ -211,5 +212,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
+# Pin this to the same major version as https://docs.python.org/3/
+Sphinx==2.4.4  # pyup: <3.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/docker/documentation/Dockerfile

@@ -1,3 +1,3 @@
-FROM python:2-stretch
+FROM python:3.8-buster
 
-RUN apt-get update && apt-get install --yes git
+RUN apt-get update && apt-get install --yes git virtualenv