doc: prepare for read_the_docs theme change

Add infrastructure for switching production documentation to use the
cleaner read_the_docs theme as noted in issue #6774.  This change won't
affect the current "daily" or "release" builds but will change local
builds that previously also used the RTD theme, but now have the version
selection capability added.

This PR also adds the Zephyr logo and favicon to the RTD-themed docs,
and moves the top level images into an images/ folder.

Note that issue #9128 requires workaround.rst to force a reference to
files needed for the build but not directly referened in a .rst file.
(When #9128 is fixed, we can remove this workaround.rst.)

Once merged and tested, we'll tweak the conf.py to use the RTD theme
for all doc builds (e.g, when DOC_TAG=daily or release) in a subsequent
PR.

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

doc/404.rst

@@ -3,7 +3,7 @@
 Sorry, Page Not Found
 #####################
 
-.. image:: Zephyr-Kite-in-tree.png
+.. image:: images/Zephyr-Kite-in-tree.png
    :align: right
    :scale: 30 %
 

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

@@ -183,12 +183,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_logo_line_small.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,
@@ -363,6 +363,14 @@ html_context = {
     'show_license': html_show_license,
     'docs_title': docs_title,
     'is_release': is_release,
+    'theme_logo_only': True,
+    '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', ''),

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;

doc/workaround.rst

@@ -0,0 +1,10 @@
+:orphan:
+
+.. Problem with the CMake build process for docs (issue #9128) not copying
+   files that aren't referenced in a .rst file over to the out-of-tree
+   build folder.  This .rst file tricks the script to reference file
+   that are mentioned in the conf.py file but not in any .rst file
+
+   .. image:: images/zephyr_logo_line_small.png
+   .. image:: images/zp_favicon.png
+   .. include:: _templates/versions.html