Provide dropdown menu which allows switching doc release

Currently deprecation badge headers just point back to the root of
the documentation for the latest stable release, so for example the
badge at the top of

    https://docs.openstack.org/latest/user/index.html

just points to

    https://docs.openstack.org/rocky/

It's useful to be able to quickly jump between different releases of
the same documentation page, but currently this requires hand-editing
URLs or many extra manual hops in the navigation trail.  So
automatically generate the links, but only display them if the link
target exists.

Since the main portal page for each release already had a "More
Releases" dropdown, remove that to avoid two dropdowns on the portal
pages.

Change-Id: I2498f00a6c863d078a70289a655b0aa3958325ed

doc/doc-contrib-guide/source/doc-tools/template-generator.rst

@@ -121,7 +121,7 @@ Here are a few representative files under ``www/``:
   * ``contributor_guides.tmpl``
   * ``css.tmpl``
   * ``default.tmpl``
-  * ``dropdown_releases_and_languages.tmpl``
+  * ``dropdown_languages.tmpl``
   * ``footer.tmpl``
   * ``google_analytics.tmpl``
   * ``header.tmpl``

tools/www-generator.py

@@ -474,7 +474,7 @@ def _get_official_repos():
 
 
 def render_template(environment, project_data, regular_repos, infra_repos,
-                    template_file, output_directory, extra={}):
+                    template_files, template_file, output_directory, extra={}):
     logger = logging.getLogger()
     logger.info("generating %s", template_file)
 
@@ -490,15 +490,18 @@ def render_template(environment, project_data, regular_repos, infra_repos,
     series_match = SERIES_PAT.match(template_file)
     if series_match:
         series = series_match.groups()[0]
+        series_path_prefix = series
         series_title = series.title()
         series_info = SERIES_INFO[series]
         if series == SERIES_IN_DEVELOPMENT:
             series = 'latest'
     else:
         series = None
+        series_path_prefix = None
         series_title = ''
         series_info = SeriesInfo('', '')
-    logger.info('series = %s', series)
+    logger.info('series = %s, path prefix = %s, title = %s',
+                series, series_path_prefix, series_title)
 
     try:
         template = environment.get_template(template_file)
@@ -511,6 +514,7 @@ def render_template(environment, project_data, regular_repos, infra_repos,
         output = template.render(
             PROJECT_DATA=project_data,
             TEMPLATE_FILE=template_file,
+            TEMPLATE_FILES={f: True for f in template_files},
             REGULAR_REPOS=regular_repos,
             INFRA_REPOS=infra_repos,
             ALL_SERIES=ALL_SERIES,
@@ -523,6 +527,7 @@ def render_template(environment, project_data, regular_repos, infra_repos,
             CSSDIR=cssdir,
             IMAGEDIR=imagedir,
             SERIES=series,
+            SERIES_PATH_PREFIX=series_path_prefix,
             SERIES_TITLE=series_title,
             SERIES_INFO=series_info,
             **extra
@@ -585,7 +590,8 @@ def main():
     # Render the templates.
     output_pages = []
     page_list_template = None
-    for template_file in environment.list_templates():
+    template_files = environment.list_templates()
+    for template_file in template_files:
         if (template_file.startswith('static/') or
                 template_file.startswith('templates/')):
             logger.info('ignoring %s', template_file)
@@ -600,6 +606,7 @@ def main():
             project_data,
             regular_repos,
             infra_repos,
+            template_files,
             template_file,
             args.output_directory,
         )
@@ -612,6 +619,7 @@ def main():
             project_data,
             regular_repos,
             infra_repos,
+            template_files,
             page_list_template,
             args.output_directory,
             extra={

www/de/index.html

@@ -33,7 +33,7 @@
                     <p>Auf dieser Seite finden Sie die auf Deutsch übersetzten OpenStack Dokumente. Bitte beachten Sie, dass noch nicht alle Dokumente auf Deutsch zur Verfügung stehen und Sie durch Verweise auf andere Dokumente auch in den englischsprachigen Originalen landen können. Weitere Sprachen und Releases finden Sie über den Button rechts.</p>
                     <p>Das Team hat sich darauf geeinigt, Fachbegriffe soweit möglich zu übersetzen. Nur Begriffe, deren Übersetzung nicht sinnvoll erscheint (z.B. Kommandos oder in der Gemeinschaft übliche Ausdrücke), bleiben unübersetzt. Hier finden Sie das vom Team gepflegte <a href="https://wiki.openstack.org/wiki/German_Translation_Dictionary">Wörterbuch</a>.</p>
                 </div>
-                {% include 'templates/dropdown_releases_and_languages.tmpl' %}
+                {% include 'templates/dropdown_languages.tmpl' %}
             </div>
         </div>
     </div>

www/fr/index.html

@@ -32,7 +32,7 @@
                     <h2> Documentation en Français</h2>
                     <p>Cette page contient la liste des documentations OpenStack disponibles en version française. Documents that have not been translated, translated into different languages, or English version of the previous releases can be found in the following menu.</p>
                 </div>
-                {% include 'templates/dropdown_releases_and_languages.tmpl' %}
+                {% include 'templates/dropdown_languages.tmpl' %}
             </div>
         </div>
     </div>

www/id/index.html

@@ -32,7 +32,7 @@
                 <h2>Dokumen Indonesia</h2>
                 <p>Ini adalah rilis Indonesian terbaru. Gunakan menu untuk memilih rilis sebelumnya atau bahasa yang berbeda jika diperlukan.</p>
             </div>
-            {% include 'templates/dropdown_releases_and_languages.tmpl' %}
+            {% include 'templates/dropdown_languages.tmpl' %}
         </div>
     </div>
 </div>

www/ja/index.html

@@ -32,7 +32,7 @@
                     <h2>日本語ドキュメント</h2>
                     <p>このページは最新版の日本語ドキュメントのみを掲載しています。すべての英語ドキュメントは<a href="https://docs.openstack.org">ドキュメントのホームページ</a>から参照できます。</p>
                 </div>
-                {% include 'templates/dropdown_releases_and_languages.tmpl' %}
+                {% include 'templates/dropdown_languages.tmpl' %}
             </div>
         </div>
     </div>

www/ko_KR/index.html

@@ -32,7 +32,7 @@
                 <h2>한국어 문서</h2>
                 <p>한국어 문서는 최신 버전만 제공합니다. 번역되지 않았거나 이전 릴리즈의 영어 문서와 다른 언어로 된 문서는 다음 메뉴에서 확인할 수 있습니다.</p>
             </div>
-            {% include 'templates/dropdown_releases_and_languages.tmpl' %}
+            {% include 'templates/dropdown_languages.tmpl' %}
         </div>
     </div>
 </div>

www/mitaka/de/index.html

@@ -33,7 +33,7 @@
                     <p>Auf dieser Seite finden Sie die auf Deutsch übersetzten OpenStack Dokumente. Bitte beachten Sie, dass noch nicht alle Dokumente auf Deutsch zur Verfügung stehen und Sie durch Verweise auf andere Dokumente auch in den englischsprachigen Originalen landen können. Weitere Sprachen und Releases finden Sie über den Button rechts.</p>
                     <p>Das Team hat sich darauf geeinigt, Fachbegriffe soweit möglich zu übersetzen. Nur Begriffe, deren Übersetzung nicht sinnvoll erscheint (z.B. Kommandos oder in der Gemeinschaft übliche Ausdrücke), bleiben unübersetzt. Hier finden Sie das vom Team gepflegte <a href="https://wiki.openstack.org/wiki/German_Translation_Dictionary">Wörterbuch</a>.</p>
                 </div>
-                {% include 'templates/dropdown_releases_and_languages.tmpl' %}
+                {% include 'templates/dropdown_languages.tmpl' %}
             </div>
         </div>
     </div>

www/newton/de/index.html

@@ -33,7 +33,7 @@
                     <p>Auf dieser Seite finden Sie die auf Deutsch übersetzten OpenStack Dokumente. Bitte beachten Sie, dass noch nicht alle Dokumente auf Deutsch zur Verfügung stehen und Sie durch Verweise auf andere Dokumente auch in den englischsprachigen Originalen landen können. Weitere Sprachen und Releases finden Sie über den Button rechts.</p>
                     <p>Das Team hat sich darauf geeinigt, Fachbegriffe soweit möglich zu übersetzen. Nur Begriffe, deren Übersetzung nicht sinnvoll erscheint (z.B. Kommandos oder in der Gemeinschaft übliche Ausdrücke), bleiben unübersetzt. Hier finden Sie das vom Team gepflegte <a href="https://wiki.openstack.org/wiki/German_Translation_Dictionary">Wörterbuch</a>.</p>
                 </div>
-                {% include 'templates/dropdown_releases_and_languages.tmpl' %}
+                {% include 'templates/dropdown_languages.tmpl' %}
             </div>
         </div>
     </div>

www/ocata/de/index.html

@@ -33,7 +33,7 @@
                     <p>Auf dieser Seite finden Sie die auf Deutsch übersetzten OpenStack Dokumente. Bitte beachten Sie, dass noch nicht alle Dokumente auf Deutsch zur Verfügung stehen und Sie durch Verweise auf andere Dokumente auch in den englischsprachigen Originalen landen können. Weitere Sprachen und Releases finden Sie über den Button rechts.</p>
                     <p>Das Team hat sich darauf geeinigt, Fachbegriffe soweit möglich zu übersetzen. Nur Begriffe, deren Übersetzung nicht sinnvoll erscheint (z.B. Kommandos oder in der Gemeinschaft übliche Ausdrücke), bleiben unübersetzt. Hier finden Sie das vom Team gepflegte <a href="https://wiki.openstack.org/wiki/German_Translation_Dictionary">Wörterbuch</a>.</p>
                 </div>
-                {% include 'templates/dropdown_releases_and_languages.tmpl' %}
+                {% include 'templates/dropdown_languages.tmpl' %}
             </div>
         </div>
     </div>

www/static/common/css/combined.css

@@ -3528,7 +3528,6 @@ input.docs-main-search:-ms-input-placeholder {
   background: #2A4E68;
   padding: 20px 5px;
   text-align: center;
-  font-size: 13px;
   color: white; }
 
 .docs-dropdown a {
@@ -3550,7 +3549,7 @@ input.docs-main-search:-ms-input-placeholder {
   font-size: 18px; }
 
 .docs-dropdown .dropdown-menu {
-  width: 150%;
+  width: 280%;
   margin-top: 10px; }
 
 .docs-dropdown > .dropdown-menu:after, .docs-dropdown > .dropdown-menu:before, .docs-sidebar-dropdown:before, .docs-sidebar-dropdown:after {

www/static/common/css/deprecated-badge.css

@@ -13,6 +13,23 @@
     margin-top: 8px;
 }
 
+.deprecated-badge .docs-dropdown {
+    display: inline-block;
+}
+
+.deprecated-badge .docs-dropdown > a {
+  padding: 5px 12px;
+  margin: 0px 4px 0px 4px;
+  width: inherit; }
+
+.deprecated-badge .docs-dropdown .dropdown-menu a {
+  padding: 5px 25px;
+  margin-top: 0px; }
+
+.deprecated-badge .docs-dropdown > .dropdown-menu > li.current {
+  padding: 5px 25px;
+  text-align: left; }
+
 .deprecated-badge a:hover {
     text-decoration: underline;
 }
@@ -25,8 +42,8 @@
     z-index: 1000;
 }
 
-p.deprecated-badge-left {
+.deprecated-badge p {
-    float: left;
+    display: inline-block;
 }
 
 a.deprecated-badge-right {
@@ -72,7 +89,7 @@ a.deprecated-badge-right {
 }
 
 .deprecated-badge-current a, .deprecated-badge-current p {
-  color: #edf2f7 !important;
+  color: #edf2f7;
 }
 
 .deprecated-badge .container

www/templates/deprecated_badge.tmpl

@@ -17,28 +17,28 @@
     ">
     <span id="deprecated-badge-close-button" title="close" class="deprecated-badge-close-button">x</span>
     <div class="container">
-       {% if SERIES_INFO.status == 'obsolete' %}
+        <div class="col-lg-12 col-md-12 col-sm-12">
-           <p class="deprecated-badge-left">
+            {% if SERIES_PATH_PREFIX %}
-                This release is no longer supported by the community. The current supported release is <a href="/{{RELEASED_SERIES}}/">{{RELEASED_SERIES.capitalize()}}.</a>
+            <p>Currently viewing</p>
-           </p>
+            {% include 'templates/switch_releases.tmpl' %}
-       {% elif SERIES_INFO.status == 'EOL' %}
+            <p>
-            <p class="deprecated-badge-left">
+            {% if SERIES_INFO.status == 'obsolete' %}
-                This release is no longer supported by the community. The current supported release is <a href="/{{RELEASED_SERIES}}/">{{RELEASED_SERIES.capitalize()}}.</a>
+                which is no longer supported by the community. The current supported release is <a href="/{{RELEASED_SERIES}}/">{{RELEASED_SERIES.capitalize()}}.</a>
-            </p>
+                </p>
-        {% elif SERIES == RELEASED_SERIES %}
+            {% elif SERIES_INFO.status == 'EOL' %}
-            <p class="deprecated-badge-left">
+                which is no longer supported by the community. The current supported release is <a href="/{{RELEASED_SERIES}}/">{{RELEASED_SERIES.capitalize()}}.</a>
-                This is the current supported release.
+            {% elif SERIES == RELEASED_SERIES %}
-            </p>
+                which is the current supported release.
-        {% elif SERIES_INFO.status == 'maintained' %}
+            {% elif SERIES_INFO.status == 'maintained' %}
-            <p class="deprecated-badge-left">
+                which is maintained, but old. The current supported
-                This is maintained, but <strong>not</strong> the current release. The current supported
                 release is <a href="/{{RELEASED_SERIES}}/">{{RELEASED_SERIES.capitalize()}}.</a>
+            {% elif SERIES_INFO.status == 'development' %}
+                which is in development. The current supported release is
+                    <a href="/{{RELEASED_SERIES}}">{{RELEASED_SERIES.capitalize()}}.</a>
+            {% endif %}
             </p>
-        {% elif SERIES_INFO.status == 'development' %}
+            {% endif %}
-            <p class="deprecated-badge-left">
+            <a href="#top" class="deprecated-badge-right"><i class="fa fa-chevron-up" aria-hidden="true"></i>&nbsp;Back to Top</a>
-                This release is under development. The current supported release is <a href="/{{RELEASED_SERIES}}/">{{RELEASED_SERIES.capitalize()}}.</a>
+        </div>
-            </p>
-        {% endif %}
-        <a href="#top" class="deprecated-badge-right"><i class="fa fa-chevron-up" aria-hidden="true"></i>&nbsp;Back to Top</a>
     </div>
 </div>

www/templates/dropdown_languages.tmpl

@@ -1,14 +1,3 @@
-            <div class="col-lg-2 col-md-2 col-sm-2">
-                <div class="dropdown docs-dropdown">
-                  <a data-toggle="dropdown" href="#">More Releases <i class="fa fa-caret-down fa-3"></i></a>
-                  <ul class="dropdown-menu" role="menu" aria-labelledby="dLabel">
-                    <li role="presentation"><a role="menuitem" tabindex="-1" href="/{{SERIES_IN_DEVELOPMENT}}/">{{SERIES_IN_DEVELOPMENT|title}} (under development)</a></li>
-{% for series_name in PAST_SERIES|reverse %}
-                    <li role="presentation"><a role="menuitem" tabindex="-1" href="/{{series_name}}/">{{series_name|title}}{% if series_name == RELEASED_SERIES %} (current release){% endif %}</a></li>
-{% endfor %}
-                  </ul>
-                </div>
-            </div>
             <div class="col-lg-2 col-md-2 col-sm-2">
                 <div class="dropdown docs-dropdown">
                   <a data-toggle="dropdown" href="#">Languages <i class="fa fa-caret-down fa-3"></i></a>

www/templates/indexbase.tmpl

@@ -43,7 +43,7 @@
             <h2>Documentation for {{SERIES_TITLE}} ({{SERIES_INFO.date}})</h2>
             {% include "templates/series_status.tmpl" %}
           </div>
-          {% include 'templates/dropdown_releases_and_languages.tmpl' %}
+          {% include 'templates/dropdown_languages.tmpl' %}
         </div>
       </div>
     </div>

www/templates/series_status.tmpl

@@ -30,15 +30,15 @@
 </p>
 
 {% elif SERIES == RELEASED_SERIES %}
-<p>This is the latest release. Use the menu to select a prior release
+<p>This is the latest release. Use the top menu to select a prior release
   if needed.</p>
 
 {% elif SERIES_INFO.status == 'maintained' %}
-<p>This is not the latest release. Use the menu to select a different
+<p>This is not the latest release. Use the top menu to select a different
   release if needed.</p>
 
 {% elif SERIES_INFO.status == 'development' %}
-<p>This release is currently under development. Use the menu to select
+<p>This release is currently under development. Use the top menu to select
   a different release if needed.</p>
 
 {% endif %}

www/templates/switch_releases.tmpl

@@ -0,0 +1,42 @@
+                <div class="dropdown docs-dropdown">
+                    <a data-toggle="dropdown" href="#">
+                    {% if SERIES_INFO.status == 'development' %}
+                        {{SERIES_IN_DEVELOPMENT|title}}
+                    {% else %}
+                        {{SERIES|title}}
+                    {% endif %}
+                    <i class="fa fa-caret-down fa-3"></i></a>
+                    <ul class="dropdown-menu" role="menu" aria-labelledby="dLabel">
+                        {% if SERIES_INFO.status == 'development' %}
+                        <li role="presentation" class="current">
+                            <span role="menuitem" tabindex="-1">
+                                {{SERIES_IN_DEVELOPMENT|title}}
+                                (viewing, in development)</span>
+                        </li>
+                        {% else %}
+                        <li role="presentation">
+                            {% set devtarget=TEMPLATE_FILE.replace(SERIES_PATH_PREFIX, SERIES_IN_DEVELOPMENT) %}
+                            <a role="menuitem" tabindex="-1"
+                               href="{{TOPDIR}}{{devtarget}}">{{SERIES_IN_DEVELOPMENT|title}}
+                               (in development)</a>
+                            {% endif %}
+                        </li>
+                    {% for series_name in PAST_SERIES|reverse %}
+                        {% set target=TEMPLATE_FILE.replace(SERIES_PATH_PREFIX, series_name) %}
+                        {% if series_name == SERIES %}
+                        <li role="presentation" class="current">
+                            {{series_name|title}}
+                            {% if series_name == RELEASED_SERIES %}
+                                (viewing, current release)
+                            {% else %}
+                                (viewing)
+                            {% endif %}
+                        {% elif TEMPLATE_FILES[target] %}
+                        <li role="presentation">
+                            <a role="menuitem" tabindex="-1"
+                               href="{{TOPDIR}}{{target}}">{{series_name|title}}{% if series_name == RELEASED_SERIES %} (current release){% endif %}</a>
+                        {% endif %}
+                        </li>
+                    {% endfor %}
+                    </ul>
+                </div>

www/tr_TR/index.html

@@ -32,7 +32,7 @@
                 <h2>Türkçe Belgeler</h2>
                 <p>Bu en son Türkçe belgeleri yayınıdır. Menüyü kullanarak önceki sürümleri veya farklı dilleri seçebilirsiniz.</p>
             </div>
-            {% include 'templates/dropdown_releases_and_languages.tmpl' %}
+            {% include 'templates/dropdown_languages.tmpl' %}
         </div>
     </div>
 </div>

www/zh_CN/index.html

@@ -32,7 +32,7 @@
                     <h2>中文</h2>
                     <p>最新的中文文档。包括安装手册，API文档</p>
                 </div>
-                {% include 'templates/dropdown_releases_and_languages.tmpl' %}
+                {% include 'templates/dropdown_languages.tmpl' %}
             </div>
         </div>
     </div>