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>
This commit is contained in:
David B. Kinder 2018-07-26 13:30:42 -07:00 committed by Anas Nashif
commit d47bd0b5c3
8 changed files with 148 additions and 3 deletions

View file

@ -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 %

28
doc/_templates/versions.html vendored Normal file
View file

@ -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>

View file

@ -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', ''),

View file

Before

Width:  |  Height:  |  Size: 321 KiB

After

Width:  |  Height:  |  Size: 321 KiB

Before After
Before After

Binary file not shown.

After

Width:  |  Height:  |  Size: 4.1 KiB

BIN
doc/images/zp_favicon.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 534 B

View file

@ -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;

10
doc/workaround.rst Normal file
View file

@ -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