Merge pull request #376 from rtfd/prepare-0.2.4

Pinning 0.2.4 release

.gitignore

@@ -6,6 +6,7 @@
 .coverage
 *.DS_Store
 *.sass-cache
+.ropeproject/
 .ruby-version
 dist/
 bower_components/

.travis.yml

@@ -0,0 +1,11 @@
+language: python
+python:
+  - 2.7
+  - 3.4
+  - 3.5
+  - 3.6
+sudo: false
+install:
+  - pip install tox-travis
+script:
+  - tox

README.rst

@@ -17,12 +17,11 @@ Read the Docs Sphinx Theme
 
 View a working demo_ over on readthedocs.org_.
 
-This is a mobile-friendly sphinx_ theme I made for readthedocs.org_. It's
-currently in development there and includes some rtd variable checks that can be ignored
-if you're just trying to use it on your project outside of that site.
+This is a mobile-friendly sphinx_ theme I made for readthedocs.org_.
 
-**This repo also exists as a submodule within the readthedocs itself**, so please make your edits to
-the SASS files here, rather than the .css files on RTD.
+If you'd like to update the theme,
+please make your edits to the SASS files here,
+rather than the .css files on checked into the repo.
 
 .. image:: screen_mobile.png
     :width: 100%
@@ -49,6 +48,15 @@ In your ``conf.py`` file:
 
     html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
+You may also specify a canonical url in conf.py to let search engines know
+they should give higher ranking to latest version of the docs:
+
+.. code:: python
+
+    html_theme_options['canonical_url'] = 'http://domain.tld/latest/docs/'
+
+The url points to the root of the documentation. It requires a trailing slash.
+
 Via git or download
 -------------------
 
@@ -97,6 +105,23 @@ Changelog
 master
 ------
 
+v0.2.4
+------
+
+* Yet another patch to deal with extra builders outside Spinx, such as the
+  singlehtml builders from the Read the Docs Sphinx extension
+
+v0.2.3
+------
+
+* Temporarily patch Sphinx issue with ``singlehtml`` builder by inspecting the
+  builder in template.
+
+v0.2.2
+------
+
+* Roll back toctree fix in 0.2.1 (#367). This didn't fix the issue and
+  introduced another bug with toctrees display.
 
 v0.2.1
 ------

setup.py

@@ -11,11 +11,11 @@ from sphinx_rtd_theme import __version__
 setup(
     name='sphinx_rtd_theme',
     version=__version__,
-    url='https://github.com/snide/sphinx_rtd_theme/',
+    url='https://github.com/rtfd/sphinx_rtd_theme/',
     license='MIT',
     author='Dave Snider',
     author_email='dave.snider@gmail.com',
-    description='ReadTheDocs.org theme for Sphinx, 2013 version.',
+    description='Read the Docs theme for Sphinx',
     long_description=open('README.rst').read(),
     zip_safe=False,
     packages=['sphinx_rtd_theme'],
@@ -28,13 +28,17 @@ setup(
     ]},
     include_package_data=True,
     classifiers=[
-        'Development Status :: 3 - Alpha',
-        'License :: OSI Approved :: BSD License',
+        'Development Status :: 5 - Production/Stable',
+        'License :: OSI Approved :: MIT License',
         'Environment :: Console',
         'Environment :: Web Environment',
         'Intended Audience :: Developers',
         'Programming Language :: Python :: 2.7',
         'Programming Language :: Python :: 3',
+        'Programming Language :: Python :: 3.3',
+        'Programming Language :: Python :: 3.4',
+        'Programming Language :: Python :: 3.5',
+        'Programming Language :: Python :: 3.6',
         'Operating System :: OS Independent',
         'Topic :: Documentation',
         'Topic :: Software Development :: Documentation',

sphinx_rtd_theme/__init__.py

@@ -5,7 +5,7 @@ From https://github.com/ryan-roemer/sphinx-bootstrap-theme.
 """
 import os
 
-__version__ = '0.2.2'
+__version__ = '0.2.4'
 __version_full__ = __version__
 
 

sphinx_rtd_theme/layout.html

@@ -22,6 +22,10 @@
   {% if favicon %}
     <link rel="shortcut icon" href="{{ pathto('_static/' + favicon, 1) }}"/>
   {% endif %}
+  {# CANONICAL URL #}
+  {% if theme_canonical_url %}
+    <link rel="canonical" href="{{ theme_canonical_url }}{{ pagename }}.html"/>
+  {% endif %}
 
   {# CSS #}
 
@@ -121,12 +125,18 @@
 
         <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
           {% block menu %}
-            {% set toctree = toctree(maxdepth=theme_navigation_depth|int, collapse=theme_collapse_navigation, includehidden=True) %}
-            {% if toctree %}
-                {{ toctree }}
+            {#
+              The singlehtml builder doesn't handle this toctree call when the
+              toctree is empty. Skip building this for now.
+            #}
+            {% if 'singlehtml' not in builder %}
+              {% set global_toc = toctree(maxdepth=theme_navigation_depth|int, collapse=theme_collapse_navigation, includehidden=True) %}
+            {% endif %}
+            {% if global_toc %}
+              {{ global_toc }}
             {% else %}
-                <!-- Local TOC -->
-                <div class="local-toc">{{ toc }}</div>
+              <!-- Local TOC -->
+              <div class="local-toc">{{ toc }}</div>
             {% endif %}
           {% endblock %}
         </div>

sphinx_rtd_theme/layout_old.html

@@ -126,6 +126,9 @@
     {%- if favicon %}
     <link rel="shortcut icon" href="{{ pathto('_static/' + favicon, 1) }}"/>
     {%- endif %}
+    {%- if theme_canonical_url %}
+    <link rel="canonical" href="{{ theme_canonical_url }}{{ pagename }}.html"/>
+    {%- endif %}
     {%- endif %}
 {%- block linktags %}
     {%- if hasdoc('about') %}

sphinx_rtd_theme/theme.conf

@@ -4,10 +4,11 @@ stylesheet = css/theme.css
 
 [options]
 typekit_id = hiw1hhg
-analytics_id = 
+analytics_id =
 sticky_navigation = False
 logo_only =
 collapse_navigation = False
 display_version = True
 navigation_depth = 4
 prev_next_buttons_location = bottom
+canonical_url =

tests/roots/test-basic/bar.rst

@@ -0,0 +1,2 @@
+bar
+===

tests/roots/test-basic/conf.py

@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+
+master_doc = 'index'
+exclude_patterns = ['_build']

tests/roots/test-basic/foo.rst

@@ -0,0 +1,6 @@
+foo
+===
+
+.. toctree::
+
+    bar

tests/roots/test-basic/index.rst

@@ -0,0 +1,12 @@
+test-basic
+==========
+
+.. toctree::
+
+    foo
+
+Heading
+-------
+
+Subheading
+~~~~~~~~~~

tests/roots/test-empty/conf.py

@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+
+master_doc = 'index'
+exclude_patterns = ['_build']

tests/roots/test-empty/index.rst

@@ -0,0 +1,10 @@
+test-empty
+==========
+
+.. toctree::
+
+Heading
+-------
+
+Subheading
+~~~~~~~~~~

tests/roots/test-missing-toctree/conf.py

@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+
+master_doc = 'index'
+exclude_patterns = ['_build']

tests/roots/test-missing-toctree/index.rst

@@ -0,0 +1,2 @@
+test-missing-toctree
+====================

tests/test_builders.py

@@ -0,0 +1,99 @@
+import os
+
+import pytest
+import sphinx
+from sphinx import addnodes
+from sphinx.builders.html import SingleFileHTMLBuilder, DirectoryHTMLBuilder
+
+from .util import build_all
+
+
+def test_basic():
+    for (app, status, warning) in build_all('test-basic'):
+        assert app.env.get_doctree('index').traverse(addnodes.toctree)
+        content = open(os.path.join(app.outdir, 'index.html')).read()
+
+        if isinstance(app.builder, DirectoryHTMLBuilder):
+            search = (
+                '<div class="toctree-wrapper compound">\n'
+                '<ul>\n'
+                '<li class="toctree-l1">'
+                '<a class="reference internal" href="foo/">foo</a>'
+                '<ul>\n'
+                '<li class="toctree-l2">'
+                '<a class="reference internal" href="bar/">bar</a></li>\n'
+                '</ul>\n'
+                '</li>\n'
+                '</ul>\n'
+                '</div>'
+            )
+            assert search in content
+        elif isinstance(app.builder, SingleFileHTMLBuilder):
+            search = (
+                '<div class="local-toc"><ul>\n'
+                '<li class="toctree-l1">'
+                '<a class="reference internal" href="index.html#document-foo">foo</a>'
+                '<ul>\n'
+                '<li class="toctree-l2">'
+                '<a class="reference internal" href="index.html#document-bar">bar</a>'
+                '</li>\n'
+                '</ul>'
+            )
+            assert search in content
+        else:
+            search = (
+                '<div class="toctree-wrapper compound">\n'
+                '<ul>\n'
+                '<li class="toctree-l1">'
+                '<a class="reference internal" href="foo.html">foo</a>'
+                '<ul>\n'
+                '<li class="toctree-l2">'
+                '<a class="reference internal" href="bar.html">bar</a></li>\n'
+                '</ul>\n'
+                '</li>\n'
+                '</ul>\n'
+                '</div>'
+            )
+            assert search in content, ('Missing search with builder {0}'
+                                       .format(app.builder.name))
+
+
+def test_empty():
+    """Local TOC is showing, as toctree was empty"""
+    for (app, status, warning) in build_all('test-empty'):
+        assert app.env.get_doctree('index').traverse(addnodes.toctree)
+        content = open(os.path.join(app.outdir, 'index.html')).read()
+        if sphinx.version_info < (1, 4):
+            if isinstance(app.builder, SingleFileHTMLBuilder):
+                assert '<div class="toctree-wrapper compound">\n</div>' in content
+                assert '<div class="local-toc">' in content
+            else:
+                global_toc = (
+                    '<div class="toctree-wrapper compound">\n'
+                    '<ul class="simple">\n</ul>\n'
+                    '</div>'
+                )
+                local_toc = (
+                    '<div class="local-toc"><ul class="simple">'
+                    '</ul>\n</div>'
+                )
+                assert global_toc in content
+                assert local_toc not in content
+        else:
+            global_toc = '<div class="toctree-wrapper compound">\n</div>'
+            local_toc = (
+                '<div class="local-toc"><ul>\n'
+                '<li><a class="reference internal" href="#">test-empty</a></li>'
+                '</ul>\n</div>'
+            )
+            assert global_toc in content
+            assert local_toc not in content
+
+
+def test_missing_toctree():
+    """Local TOC is showing, as toctree was missing"""
+    for (app, status, warning) in build_all('test-missing-toctree'):
+        assert app.env.get_doctree('index').traverse(addnodes.toctree) == []
+        content = open(os.path.join(app.outdir, 'index.html')).read()
+        assert '<div class="toctree' not in content
+        assert '<div class="local-toc">' in content

tests/util.py

@@ -0,0 +1,60 @@
+from __future__ import print_function
+
+import os
+import tempfile
+import shutil
+from contextlib import contextmanager
+
+import pytest
+from sphinx.application import Sphinx
+
+try:
+    from StringIO import StringIO
+except ImportError:
+    from io import StringIO
+
+
+@contextmanager
+def build(root, builder='html', **kwargs):
+    tmpdir = tempfile.mkdtemp()
+
+    srcdir = os.path.join(os.path.dirname(__file__), 'roots', root)
+    destdir = os.path.join(tmpdir, builder)
+    doctreedir = os.path.join(tmpdir, 'doctree/')
+
+    status = StringIO()
+    warning = StringIO()
+
+    kwargs.update({
+        'status': status,
+        'warning': warning,
+    })
+
+    confoverrides = kwargs.pop('confoverrides', {})
+    confoverrides['html_theme'] = 'sphinx_rtd_theme'
+    extensions = confoverrides.get('extensions', [])
+    extensions.append('readthedocs_ext.readthedocs')
+    confoverrides['extensions'] = extensions
+    kwargs['confoverrides'] = confoverrides
+
+    try:
+        app = Sphinx(srcdir, srcdir, destdir, doctreedir, builder, **kwargs)
+        app.builder.build_all()
+        yield (app, status.getvalue(), warning.getvalue())
+    except Exception as e:
+        print('# root:', root)
+        print('# builder:', builder)
+        print('# source:', srcdir)
+        print('# destination:', destdir)
+        print('# status:', '\n' + status.getvalue())
+        print('# warning:', '\n' + warning.getvalue())
+        raise
+    finally:
+        shutil.rmtree(tmpdir)
+
+
+def build_all(root, **kwargs):
+    for builder in ['html', 'singlehtml', 'readthedocs', 'readthedocsdirhtml',
+                    'readthedocssinglehtml', 'readthedocssinglehtmllocalmedia']:
+        with build(root, builder, **kwargs) as ret:
+            yield ret

tox.ini

@@ -0,0 +1,21 @@
+[tox]
+envlist = py{27,34,35,36}-sphinx{13,14,15}
+
+[tox:travis]
+2.7 = py27-sphinx{13,14,15}
+3.4 = py34-sphinx{13,14,15}
+3.5 = py35-sphinx{13,14,15}
+3.6 = py36-sphinx{13,14,15}
+
+[testenv]
+setev =
+    LANG=C
+deps =
+    .
+    readthedocs-sphinx-ext
+    pytest
+    sphinx13: Sphinx < 1.4
+    sphinx14: Sphinx < 1.5
+    sphinx15: Sphinx < 1.6
+commands =
+    py.test {posargs}