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/docs/conf.py b/docs/conf.py index de2f60cfa5..d6e37faf4f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,14 +1,14 @@ # 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 master_doc = "index" project = "Tornado" -copyright = "2009-%s, The Tornado Authors" % time.strftime("%Y") +copyright = "The Tornado Authors" version = release = tornado.version @@ -20,8 +20,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 +42,12 @@ coverage_ignore_classes = [ # tornado.gen "Runner", - # tornado.web "ChunkedTransferEncoding", "GZipContentEncoding", "OutputTransform", "TemplateModule", "url", - # tornado.websocket "WebSocketProtocol", "WebSocketProtocol13", @@ -60,32 +58,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()] 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 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