From da46f68d5b82371132b4f877e05b9b457de89af9 Mon Sep 17 00:00:00 2001 From: ziransun Date: Thu, 26 Nov 2020 19:55:09 +0000 Subject: [PATCH] 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 (https://github.com/sphinx-doc/sphinx/issues/2549) b) Fix Sphinx in third_party/pywebsocket3. A PR has been sent at https://github.com/GoogleChromeLabs/pywebsocket3/pull/16 Note: Command to run with Python3 is: wpt --py3 build-docs Co-authored-by: Robert Ma --- docs/conf.py | 3 ++- docs/requirements.txt | 4 ++-- docs/reviewing-tests/checklist.md | 2 +- docs/wpt_lint_rules.py | 3 ++- tools/docker/documentation/Dockerfile | 4 ++-- 5 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 44d3c2f76bbcd6..96e8290455e20c 100644 --- a/docs/conf.py +++ b/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)} diff --git a/docs/requirements.txt b/docs/requirements.txt index a9ddeecfe57382..03ce983831da5d 100644 --- a/docs/requirements.txt +++ b/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 diff --git a/docs/reviewing-tests/checklist.md b/docs/reviewing-tests/checklist.md index 0e50843f289bfa..be0f4d134e4d3d 100644 --- a/docs/reviewing-tests/checklist.md +++ b/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. diff --git a/docs/wpt_lint_rules.py b/docs/wpt_lint_rules.py index a5eed507b5e774..b9997372520f36 100644 --- a/docs/wpt_lint_rules.py +++ b/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 diff --git a/tools/docker/documentation/Dockerfile b/tools/docker/documentation/Dockerfile index e01f98e4d4df0e..01ea0bd95bf6d1 100644 --- a/tools/docker/documentation/Dockerfile +++ b/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