From e99eeb4e317b835f5e072750d8f858c368d27d0d Mon Sep 17 00:00:00 2001 From: Ben Darnell Date: Sat, 29 Dec 2018 19:54:51 -0500 Subject: [PATCH 1/4] docs: Upgrade sphinx to 1.8 The bug that kept us on 1.7 was fixed in 1.8.2. --- docs/requirements.txt | 3 +-- maint/requirements.in | 2 +- maint/requirements.txt | 2 +- 3 files changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/requirements.txt b/docs/requirements.txt index d5626da3cf..69c93b12cc 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,4 +1,3 @@ -# https://bugs.python.org/issue34700 -sphinx<1.8.0 +sphinx>1.8.2 sphinx_rtd_theme Twisted diff --git a/maint/requirements.in b/maint/requirements.in index 094f7ca50c..87caccd2a0 100644 --- a/maint/requirements.in +++ b/maint/requirements.in @@ -11,7 +11,7 @@ pycares pycurl # Other useful tools -Sphinx<1.8.0 +Sphinx>1.8.2 autopep8 black coverage diff --git a/maint/requirements.txt b/maint/requirements.txt index 17b8f37867..f8d3399399 100644 --- a/maint/requirements.txt +++ b/maint/requirements.txt @@ -41,7 +41,7 @@ requests==2.20.0 requests-toolbelt==0.8.0 six==1.11.0 snowballstemmer==1.2.1 -Sphinx==1.7.9 +Sphinx==1.8.3 sphinx-rtd-theme==0.4.2 sphinxcontrib-websupport==1.1.0 toml==0.10.0 From cb2d8977e53ad36eba730ebf9bd8d790cb835540 Mon Sep 17 00:00:00 2001 From: Ben Darnell Date: Sat, 29 Dec 2018 19:55:27 -0500 Subject: [PATCH 2/4] docs: Blacken conf.py --- docs/conf.py | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index de2f60cfa5..3de27ebac1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -2,6 +2,7 @@ import os import sys import time + sys.path.insert(0, os.path.abspath("..")) import tornado @@ -20,8 +21,8 @@ "sphinx.ext.viewcode", ] -primary_domain = 'py' -default_role = 'py:obj' +primary_domain = "py" +default_role = "py:obj" autodoc_member_order = "bysource" autoclass_content = "both" @@ -42,14 +43,12 @@ coverage_ignore_classes = [ # tornado.gen "Runner", - # tornado.web "ChunkedTransferEncoding", "GZipContentEncoding", "OutputTransform", "TemplateModule", "url", - # tornado.websocket "WebSocketProtocol", "WebSocketProtocol13", @@ -60,32 +59,36 @@ # various modules "doctests", "main", - # tornado.escape # parse_qs_bytes should probably be documented but it's complicated by # having different implementations between py2 and py3. "parse_qs_bytes", - # tornado.gen "Multi", ] -html_favicon = 'favicon.ico' +html_favicon = "favicon.ico" latex_documents = [ - ('index', 'tornado.tex', 'Tornado Documentation', 'The Tornado Authors', 'manual', False), + ( + "index", + "tornado.tex", + "Tornado Documentation", + "The Tornado Authors", + "manual", + False, + ) ] -intersphinx_mapping = { - 'python': ('https://docs.python.org/3.6/', None), -} +intersphinx_mapping = {"python": ("https://docs.python.org/3.6/", None)} -on_rtd = os.environ.get('READTHEDOCS', None) == 'True' +on_rtd = os.environ.get("READTHEDOCS", None) == "True" # On RTD we can't import sphinx_rtd_theme, but it will be applied by # default anyway. This block will use the same theme when building locally # as on RTD. if not on_rtd: import sphinx_rtd_theme - html_theme = 'sphinx_rtd_theme' + + html_theme = "sphinx_rtd_theme" html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] From e7e31e5642ae56da3f768d9829036eab99f0c988 Mon Sep 17 00:00:00 2001 From: Ben Darnell Date: Sat, 29 Dec 2018 19:57:39 -0500 Subject: [PATCH 3/4] docs: Use python 3.7 via conda for readthedocs builds The typing module in python 3.5 has problems with some type annotations so we need to build with 3.7. RTD doesn't yet support py37 natively but we can get it with conda following an example at https://github.com/rtfd/readthedocs-docker-images/pull/73 --- docs/conda.yml | 8 ++++++++ readthedocs.yml | 4 ++++ 2 files changed, 12 insertions(+) create mode 100644 docs/conda.yml create mode 100644 readthedocs.yml diff --git a/docs/conda.yml b/docs/conda.yml new file mode 100644 index 0000000000..e33288db2a --- /dev/null +++ b/docs/conda.yml @@ -0,0 +1,8 @@ +# TODO: remove when RTD supports python 3.7 without conda +name: tornado-docs +dependencies: + - python=3.7 + - pip: + - sphinx + - sphinx-rtd-theme + - Twisted diff --git a/readthedocs.yml b/readthedocs.yml new file mode 100644 index 0000000000..e40382080b --- /dev/null +++ b/readthedocs.yml @@ -0,0 +1,4 @@ +# TODO: remove when RTD supports Python 3.7 without conda. +# https://github.com/rtfd/readthedocs-docker-images/pull/73 +conda: + file: docs/conda.yml From e5bd1c2e0e685fc822c65fce96e88542981dd1d1 Mon Sep 17 00:00:00 2001 From: Ben Darnell Date: Sat, 29 Dec 2018 19:59:20 -0500 Subject: [PATCH 4/4] docs: Remove year from copyright variable Computing this dynamically is wrong and it doesn't seem worth the trouble to maintain manually. Closes #2258 Closes #2259 --- docs/conf.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 3de27ebac1..d6e37faf4f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,7 +1,6 @@ # Ensure we get the local copy of tornado instead of what's on the standard path import os import sys -import time sys.path.insert(0, os.path.abspath("..")) import tornado @@ -9,7 +8,7 @@ master_doc = "index" project = "Tornado" -copyright = "2009-%s, The Tornado Authors" % time.strftime("%Y") +copyright = "The Tornado Authors" version = release = tornado.version