doc: update 1.12 release with RTD theme

We've replaced the "zephyr-docs" theme with a simpler read-the-docs
thema starting with the 1.13 release.  This PR retrofits the theme
changes back onto this 1.12 release and ignores attempts to use the
zephyr-docs theme controlled by the make DOC_TAGS option.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>

.known-issues/doc/duplicate.conf

@@ -0,0 +1,6 @@
+#
+^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]api[/\\]file_system.rst):(?P<lineno>[0-9]+): WARNING: Duplicate declaration.
+#
+^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]api[/\\]io_interfaces.rst):(?P<lineno>[0-9]+): WARNING: Duplicate declaration.
+#
+^(?P<filename>([\-:\\/\w\.])+[/\\]doc[/\\]subsystems[/\\]sensor.rst):(?P<lineno>[0-9]+): WARNING: Duplicate declaration.

doc/_templates/breadcrumbs.html

@@ -0,0 +1,14 @@
+{% extends "!breadcrumbs.html" %}
+{% block breadcrumbs %}
+  <!-- {{ docs_title }} -->
+  {# parameterize default name "Docs" in breadcrumb via docs_title in conf.py #}
+  {% if not docs_title %}
+  {% set docs_title = "Docs" %}
+  {% endif %}
+
+  <li><a href="{{ pathto(master_doc) }}">{{ docs_title }}</a> &raquo;</li>
+  {% for doc in parents %}
+     <li><a href="{{ doc.link|e }}">{{ doc.title }}</a> &raquo;</li>
+  {% endfor %}
+  <li>{{ title }}</li>
+{% endblock %}

doc/_templates/layout.html

@@ -0,0 +1,10 @@
+{% extends "!layout.html" %}
+{% block document %}
+  {% if is_release %}
+    <div class="wy-alert wy-alert-danger">
+      The <a href="/{{ pagename }}.html">latest development version</a>
+      of this page may be more current than this released {{ version }} version.
+    </div>
+  {% endif %}
+  {{ super() }}
+{% endblock %}

doc/_templates/versions.html

@@ -0,0 +1,28 @@
+{# 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"> Zephyr Project</span>
+      v: {{ current_version }}
+      <span class="fa fa-caret-down"></span>
+    </span>
+    <div class="rst-other-versions">
+      <dl>
+        <dt>{{ _('Versions') }}</dt>
+        {% for slug, url in versions %}
+          <dd><a href="{{ url }}">{{ slug }}</a></dd>
+        {% endfor %}
+      </dl>
+      <dl>
+        <dt>{{ _('On zephyrproject.org') }}</dt>
+          <dd>
+            <a href="https://www.zephyrproject.org/">Project Home</a>
+          </dd>
+          <dd>
+            <a href="https://www.zephyrproject.org/developers/#downloads">Downloads</a>
+          </dd>
+          <dd>
+            <a href="https://github.com/zephyrproject-rtos/zephyr/releases">Releases</a>
+          </dd>
+      </dl>
+    </div>
+  </div>

doc/conf.py

@@ -145,19 +145,9 @@ rst_epilog = """
 
 # -- Options for HTML output ----------------------------------------------
 
-try:
-    import sphinx_rtd_theme
-except ImportError:
-    html_theme = 'zephyr'
-    html_theme_path = ['./themes']
-else:
-    html_theme = "sphinx_rtd_theme"
-    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
-
-if tags.has('daily') or tags.has('release'):
-    html_theme = 'zephyr-docs-theme'
-    html_theme_path = ['./themes']
-
+import sphinx_rtd_theme
+html_theme = "sphinx_rtd_theme"
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 if tags.has('release'):
     is_release = True
@@ -179,12 +169,12 @@ html_title = "Zephyr Project Documentation"
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-#html_logo = None
+html_logo = 'images/Zephyr-Kite-logo.png'
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
-#html_favicon = None
+html_favicon = 'images/zp_favicon.png'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -221,7 +211,7 @@ html_use_index = True
 html_split_index = True
 
 # If true, links to the reST sources are added to the pages.
-#html_show_sourcelink =
+html_show_sourcelink = False
 
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
 html_show_sphinx = False
@@ -359,6 +349,14 @@ html_context = {
     'show_license': html_show_license,
     'docs_title': docs_title,
     'is_release': is_release,
+    'theme_logo_only': False,
+    'current_version': version,
+    'versions': ( ("latest", "/"),
+                 ("1.12.0", "/1.12.0/"),
+                 ("1.11.0", "/1.11.0/"),
+                 ("1.10.0", "/1.10.0/"),
+                 ("1.9.2", "/1.9.0/"),
+                )
 }
 
 extlinks = {'jira': ('https://jira.zephyrproject.org/browse/%s', ''),
@@ -379,3 +377,4 @@ linkcheck_anchors = False
 
 def setup(app):
    app.add_stylesheet("zephyr-custom.css")
+   app.add_javascript("zephyr-custom.js")

doc/static/zephyr-custom.css

@@ -1,5 +1,104 @@
 /* -- Extra CSS styles for Zephyr content (RTD theme) ----------------------- */
 
+/* make the page width fill the window */
+.wy-nav-content {
+   max-width: none;
+}
+
+/* pygments tweak for white-on-black console */
+/* hold off on this change for now
+
+.highlight-console .highlight {
+   background-color: black;
+}
+.highlight-console .highlight .go, .highlight-console .highlight .gp {
+   color: white;
+}
+.highlight-console .highlight .hll {
+   background-color: white;
+}
+.highlight-console .highlight .hll .go, .highlight-console .highlight .hll .gp {
+   color: black;
+   font-weight: bold;
+}
+*/
+
+/* tweak doc version selection
+.rst-versions {
+   position: static;
+   border-top: none;
+   padding: 0px;
+}
+*/
+
+.rst-versions .rst-current-version {
+   padding: 5px;
+   background-color: #2980B9;
+   color: #80FF80;
+}
+
+.rst-versions .rst-other-versions {
+   padding: 5px;
+}
+
+div.rst-other-versions dl {
+   margin-bottom: 0;
+}
+
+
+/* code block highlight color in rtd changed to lime green, no no no */
+
+.rst-content tt.literal, .rst-content code.literal, .highlight {
+   background: #f0f0f0;
+}
+.rst-content tt.literal, .rst-content code.literal {
+    color: #000000;
+}
+
+/* Make the version number more visible */
+.wy-side-nav-search>div.version {
+    color: rgba(255,255,255,1);
+}
+
+/* squish the space between a paragraph before a list */
+div > p + ul, div > p + ol {
+   margin-top: -20px;
+}
+
+/* add some space before the figure caption */
+p.caption  {
+#    border-top: 1px solid;
+    margin-top: 1em;
+}
+
+/* decrease line leading a bit, 24px is too wide */
+
+p {
+   line-height: 22px;
+}
+
+/* add a colon after the figure/table number (before the caption) */
+span.caption-number::after {
+   content: ": ";
+}
+
+p.extrafooter {
+   text-align: right;
+   margin-top: -36px;
+}
+
+table.align-center {
+   display: table !important;
+}
+
+
+.code-block-caption {
+    color: #000;
+    font: italic 85%/1 arial,sans-serif;
+    padding: 1em 0;
+    text-align: center;
+}
+
 /*  make .. hlist:: tables fill the page */
 table.hlist {
     width: 95% !important;
@@ -34,3 +133,24 @@ th,td {
 col.option {
   width: 25%;
 }
+
+/* tweak format for <kbd> (:kbd:`F10`) */
+kbd
+{
+  -moz-border-radius:3px;
+  -moz-box-shadow:0 1px 0 rgba(0,0,0,0.2),0 0 0 2px #fff inset;
+  -webkit-border-radius:3px;
+  -webkit-box-shadow:0 1px 0 rgba(0,0,0,0.2),0 0 0 2px #fff inset;
+  background-color:#f7f7f7;
+  border:1px solid #ccc;
+  border-radius:3px;
+  box-shadow:0 1px 0 rgba(0,0,0,0.2),0 0 0 2px #fff inset;
+  color:#333;
+  display:inline-block;
+  font-family:Arial,Helvetica,sans-serif;
+  font-size:11px;
+  line-height:1.4;
+  margin:0 .1em;
+  padding:.1em .6em;
+  text-shadow:0 1px 0 #fff;
+}

doc/static/zephyr-custom.js

@@ -0,0 +1,6 @@
+/* tweak logo link to the project home page in a new tab*/
+
+$(document).ready(function(){
+   $( ".icon-home" ).attr("href", "https://zephyrproject.org/");
+   $( ".icon-home" ).attr("target", "_blank");
+});