Merge branch 'master' into Blendify/remove-READTHEDOCS

This block would allow users to append custom html to the menu

docs/_templates/layout.html

@@ -1,55 +0,0 @@
-{%- 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/_templates/versions.html

@@ -0,0 +1,27 @@
+{%- extends "!versions.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 versions_menu_contents %}
+  {{ super() }}
+  <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>
+{%- endblock %}

docs/changelog.rst

@@ -26,6 +26,7 @@ Other Changes
 * Don't require npm to build from source (#1039)
 * Use regular toctree instead of toc for singlehtml builder (#507)
 * Templates: Cleanup Whitespace (#1060)
+* Add support for version menu outside the Read The Docs environment (#1107)
 
 Fixes
 -----

docs/conf.py

@@ -56,12 +56,12 @@ html_context = {}
 if not 'READTHEDOCS' in os.environ:
     html_static_path = ['_static/']
     html_js_files = ['debug.js']
+    html_theme_options['versions_menu'] = True
 
     # Add fake versions for local QA of the menu
-    html_context['test_versions'] = list(map(
-        lambda x: str(x / 10),
-        range(1, 100)
-    ))
+    html_context['versions'] = tuple((i,)*2 for i in range(1, 100))
+    html_context['languages'] = [('en', '/en'), ('fr', '/fr')]
+    html_context['downloads'] = [('pdf', '/pdf.pdf'), ('epub', '/epub.epub')]
 
 html_logo = "demo/static/logo-wordmark-light.svg"
 html_show_sourcelink = True

docs/configuring.rst

@@ -21,6 +21,7 @@ For example:
         'style_external_links': False,
         'vcs_pageview_mode': '',
         'style_nav_header_background': 'white',
+        'versions_menu': False,
         # Toc options
         'collapse_navigation': True,
         'sticky_navigation': True,
@@ -174,6 +175,13 @@ Miscellaneous options
     :type: string
     :default: ``#2980B9``
 
+.. confval:: versions_menu
+
+    Whether or not to show the bottom left menu listing the versions and links
+    to VCS repository.
+
+    :type: boolean
+    :default: False
 
 File-wide metadata
 ==================

sphinx_rtd_theme/layout.html

@@ -153,7 +153,7 @@
 
           {%- if theme_display_version %}
             {%- set nav_version = version %}
-            {%- if READTHEDOCS and current_version %}
+            {%- if current_version %}
               {%- set nav_version = current_version %}
             {%- endif %}
             {%- if nav_version %}
@@ -231,8 +231,7 @@
       });
   </script>
 
-  {#- Do not conflict with RTD insertion of analytics script #}
-  {%- if not READTHEDOCS %}
+  {%- block analytics %}
     {%- if theme_analytics_id %}
     <!-- Theme Analytics -->
     <script async src="https://www.googletagmanager.com/gtag/js?id={{ theme_analytics_id }}"></script>
@@ -247,7 +246,7 @@
     </script>
 
     {%- endif %}
-  {%- endif %}
+  {%- endblock %}
 
   {%- block footer %} {% endblock %}
 

sphinx_rtd_theme/theme.conf

@@ -18,3 +18,4 @@ prev_next_buttons_location = bottom
 style_external_links = False
 style_nav_header_background =
 vcs_pageview_mode =
+versions_menu = False

sphinx_rtd_theme/versions.html

@@ -1,34 +1,50 @@
-{% if READTHEDOCS %}
+{%- block versions_menu %}
+{%- if theme_versions_menu|tobool %}
 {# Add rst-badge after rst-versions for small badge style. #}
   <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: {{ current_version }}
+      {%- block versions_menu_title %}
+      <span class="fa fa-book"> {{ project }}</span>
+      v: {{ version }}
       <span class="fa fa-caret-down"></span>
+      {%- endblock %}
     </span>
     <div class="rst-other-versions">
+    {%- block versions_menu_contents %}
+      {%- block languages %}
+      {%- if languages|length >= 1 %}
+      <dl>
+        <dt>{{ _('Languages') }}</dt>
+        {%- for slug, url in languages %}
+          <dd><a href="{{ url }}">{{ slug }}</a></dd>
+        {%- endfor %}
+      </dl>
+      {%- endif %}
+      {%- endblock %} 
+
+      {%- block versions %}
+      {%- if versions|length >= 1 %}
       <dl>
         <dt>{{ _('Versions') }}</dt>
-        {% for slug, url in versions %}
+        {%- for slug, url in versions %}
           <dd><a href="{{ url }}">{{ slug }}</a></dd>
-        {% endfor %}
+        {%- endfor %}
       </dl>
+      {%- endif %}
+      {%- endblock %}
+
+      {%- block downloads %}
+      {%- if downloads|length >= 1 %}
       <dl>
         <dt>{{ _('Downloads') }}</dt>
-        {% for type, url in downloads %}
+        {%- for type, url in downloads %}
           <dd><a href="{{ url }}">{{ type }}</a></dd>
-        {% endfor %}
-      </dl>
-      <dl>
-        {# Translators: The phrase "Read the Docs" is not translated #}
-        <dt>{{ _('On Read the Docs') }}</dt>
-          <dd>
-            <a href="//{{ PRODUCTION_DOMAIN }}/projects/{{ slug }}/?fromdocs={{ slug }}">{{ _('Project Home') }}</a>
-          </dd>
-          <dd>
-            <a href="//{{ PRODUCTION_DOMAIN }}/builds/{{ slug }}/?fromdocs={{ slug }}">{{ _('Builds') }}</a>
-          </dd>
+        {%- endfor %}
       </dl>
+      {%- endif %}
+      {%- endblock %}
+    {%- endblock %}
     </div>
   </div>
-{% endif %}
+{%- endif %}
+{%- endblock %}