Merge pull request #838 from readthedocs/agj/fix-dl-styles

Address Sphinx 2 compatibility issues

.travis.yml

@@ -1,19 +1,14 @@
 language: python
 python:
   - 2.7
-  - 3.4
-  - 3.5
   - 3.6
-matrix:
-  include:
-    - python: 2.7
-      env: TOXENV=docs
+  - 3.7
 install:
   - pip install tox-travis
   - pip install sphinx
 script:
   - tox
-  
+
 branches:
   only:
   - master

docs/_static/debug.js

@@ -0,0 +1,7 @@
+// Add debug actions to flyout menu
+
+$(function () {
+  $("[data-toggle='rst-debug-badge']").on("click", function () {
+    $("[data-toggle='rst-versions']").toggleClass("rst-badge");
+  });
+})

docs/_templates/layout.html

@@ -0,0 +1,55 @@
+{%- extends "!layout.html" %}
+
+{#
+
+This template exists as a way to implement a version menu without changing what
+the theme normally renders the menu on local builds and on builds on Read the
+Docs. This is for local testing purposes only.
+
+#}
+
+{% block footer %}
+  {% if not READTHEDOCS %}
+    <div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
+      <span class="rst-current-version" data-toggle="rst-current-version">
+        <span class="fa fa-book"> Read the Docs</span>
+        v: latest
+        <span class="fa fa-caret-down"></span>
+      </span>
+      <div class="rst-other-versions">
+        <dl>
+          <dt>{{ _('Versions') }}</dt>
+          {% if test_versions %}
+            {% for version in test_versions %}
+            <dd><a href="#">{{ version }}</a></dd>
+            {% endfor %}
+          {% else %}
+            <dd><a href="#">latest</a></dd>
+            <dd><a href="#">1.0</a></dd>
+            <dd><a href="#">1.1</a></dd>
+          {% endif %}
+        </dl>
+        <dl>
+          <dt>{{ _('Downloads') }}</dt>
+          <dd><a href="#">PDF</a></dd>
+          <dd><a href="#">ePub</a></dd>
+          <dd><a href="#">HTML</a></dd>
+        </dl>
+        <dl>
+          {# Translators: The phrase "Read the Docs" is not translated #}
+          <dt>{{ _('On Read the Docs') }}</dt>
+            <dd>
+              <a href="#">{{ _('Project Home') }}</a>
+            </dd>
+            <dd>
+              <a href="#">{{ _('Builds') }}</a>
+            </dd>
+        </dl>
+        <dl>
+          <dt>Debug</dt>
+          <dd><a href="#" data-toggle="rst-debug-badge">Swap badge position</a></dd>
+        </dl>
+      </div>
+    </div>
+  {% endif %}
+{% endblock %}

docs/conf.py

@@ -4,18 +4,30 @@
 import os
 import re
 
-if not 'READTHEDOCS' in os.environ:
+# If we are building locally, or the build on Read the Docs looks like a PR
+# build, prefer to use the version of the theme in this repo, not the installed
+# version of the theme.
+def is_development_build():
+    # PR builds have an interger version
+    re_version = re.compile(r'^[\d]+$')
+    if 'READTHEDOCS' in os.environ:
+        version = os.environ.get('READTHEDOCS_VERSION', '')
+        if re_version.match(version):
+            return True
+        return False
+    return True
+
+if is_development_build():
     sys.path.insert(0, os.path.abspath('..'))
 sys.path.append(os.path.abspath('./demo/'))
 
+import sphinx_rtd_theme
 from sphinx.locale import _
-from sphinx_rtd_theme import __version__
-
 
 project = u'Read the Docs Sphinx Theme'
 slug = re.sub(r'\W+', '-', project.lower())
-version = __version__
-release = __version__
+version = sphinx_rtd_theme.__version__
+release = sphinx_rtd_theme.__version__
 author = u'Dave Snider, Read the Docs, Inc. & contributors'
 copyright = author
 language = 'en'
@@ -49,7 +61,18 @@
     'logo_only': True,
     'navigation_depth': 5,
 }
-html_theme_path = ["../.."]
+html_context = {}
+
+if not 'READTHEDOCS' in os.environ:
+    html_static_path = ['_static/']
+    html_js_files = ['debug.js']
+
+    # Add fake versions for local QA of the menu
+    html_context['test_versions'] = list(map(
+        lambda x: str(x / 10),
+        range(1, 100)
+    ))
+
 html_logo = "demo/static/logo-wordmark-light.svg"
 html_show_sourcelink = True
 

docs/requirements.txt

@@ -1,2 +1,2 @@
-sphinx
+sphinx>=3.0
 sphinxcontrib-httpdomain

setup.py

@@ -18,7 +18,7 @@ class WebpackBuildCommand(setuptools.command.build_py.build_py):
     """Prefix Python build with Webpack asset build"""
 
     def run(self):
-        if not 'CI' in os.environ:
+        if not 'CI' in os.environ and not 'TOX_ENV_NAME' in os.environ:
             subprocess.run(['npm', 'install'], check=True)
             subprocess.run(['node_modules/.bin/webpack', '--config', 'webpack.prod.js'], check=True)
         setuptools.command.build_py.build_py.run(self)

sphinx_rtd_theme/__init__.py

@@ -21,7 +21,9 @@ def get_html_theme_path():
 
 # See http://www.sphinx-doc.org/en/stable/theming.html#distribute-your-theme-as-a-python-package
 def setup(app):
-    app.add_html_theme('sphinx_rtd_theme', path.abspath(path.dirname(__file__)))
+    if sphinx.version_info >= (1, 6, 0):
+        # Register the theme that can be referenced without adding a theme path
+        app.add_html_theme('sphinx_rtd_theme', path.abspath(path.dirname(__file__)))
 
     if sphinx.version_info >= (1, 8, 0):
         # Add Sphinx message catalog for newer versions of Sphinx

sphinx_rtd_theme/layout.html

@@ -7,9 +7,10 @@
   {%- set titlesuffix = "" %}
 {%- endif %}
 {%- set lang_attr = 'en' if language == None else (language | replace('_', '-')) %}
+{%- set sphinx_writer = 'writer-html5' if html5_doctype else 'writer-html4' %}
 
 <!DOCTYPE html>
-<html lang="{{ lang_attr }}" >
+<html class="{{ sphinx_writer }}" lang="{{ lang_attr }}" >
 <head>
   <meta charset="utf-8">
   {{ metatags }}