doc: update 1.9 release with RTD theme
We've replaced the "zephyr-docs" theme with a simpler read-the-docs
theme starting with the 1.13 release. This PR retrofits the theme
changes back onto this 1.9 release and ignores attempts to use the
zephyr-docs theme controlled by the make DOC_TAGS option.
Also needed to backport changes to the warning filtering system
implemented in later releases, fixes to how the config options were
generated (genrest.py).
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
diff --git a/.known-issues/doc/duplicate.conf b/.known-issues/doc/duplicate.conf
new file mode 100644
index 0000000..6bd7dc6
--- /dev/null
+++ b/.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.
diff --git a/.known-issues/doc/networking.conf b/.known-issues/doc/networking.conf
index 1a2de22..55deabe 100644
--- a/.known-issues/doc/networking.conf
+++ b/.known-issues/doc/networking.conf
@@ -20,12 +20,12 @@
# include/net/net_if.h warnings
#
^(?P<filename>[-._/\w]+/doc/api/networking.rst):(?P<lineno>[0-9]+): WARNING: Error when parsing function declaration.
-^\If the function has no return type:
+^If the function has no return type:
^[ \t]*Error in declarator or parameters and qualifiers
^[ \t]*Invalid definition: Expected identifier in nested name, got keyword: struct \[error at [0-9]+]
^.*struct net_if __aligned\(32\)
^[- \t]*\^
-^\If the function has a return type:
+^If the function has a return type:
^[ \t]*Error in declarator or parameters and qualifiers
^[ \t]*If pointer to member declarator:
^[ \t]*Invalid definition: Expected \'::\' in pointer to member \(function\). \[error at [0-9]+]
diff --git a/boards/xtensa/esp32/doc/esp32.rst b/boards/xtensa/esp32/doc/esp32.rst
index 60b90e3..309c6a9 100644
--- a/boards/xtensa/esp32/doc/esp32.rst
+++ b/boards/xtensa/esp32/doc/esp32.rst
@@ -15,7 +15,7 @@
Tensilica Xtensa LX6 microprocessor in both dual-core and single-core
variations. ESP32 is created and developed by Espressif Systems, a
Shanghai-based Chinese company, and is manufactured by TSMC using their 40nm
- process. [1]_
+ process..
The features include the following:
@@ -171,7 +171,6 @@
References
**********
-.. [1] https://en.wikipedia.org/wiki/ESP32
.. _`ESP32 Technical Reference Manual`: https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf
.. _`JTAG debugging for ESP32`: https://espressif.com/sites/default/files/documentation/jtag_debugging_for_esp32_en.pdf
.. _`toolchain`: https://esp-idf.readthedocs.io/en/latest/get-started/index.html#get-started-setup-toochain
diff --git a/doc/Makefile b/doc/Makefile
index 624e12c..40040be 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -66,6 +66,8 @@
@rm -rf reference/kconfig/*.rst
@rm -rf samples
@rm -rf boards
+ @rm -f doc.log
+ @rm -f doc.warnings
htmldocs: doxy html
@@ -79,7 +81,8 @@
prep: doxy content kconfig
html: content kconfig
- $(Q)$(SPHINXBUILD) -t $(DOC_TAG) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ $(Q)$(SPHINXBUILD) -t $(DOC_TAG) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html 2>&1 | tee -a doc.log;
+ $(Q)./scripts/filter-doc-log.sh doc.log
@rm -rf samples
@rm -rf boards
diff --git a/doc/_templates/breadcrumbs.html b/doc/_templates/breadcrumbs.html
new file mode 100644
index 0000000..6c6493a
--- /dev/null
+++ b/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> »</li>
+ {% for doc in parents %}
+ <li><a href="{{ doc.link|e }}">{{ doc.title }}</a> »</li>
+ {% endfor %}
+ <li>{{ title }}</li>
+{% endblock %}
diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html
new file mode 100644
index 0000000..b6894ee
--- /dev/null
+++ b/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 %}
diff --git a/doc/_templates/versions.html b/doc/_templates/versions.html
new file mode 100644
index 0000000..2f265d8
--- /dev/null
+++ b/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>
diff --git a/doc/conf.py b/doc/conf.py
index ebf8d6d..fb934b9 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -143,19 +143,9 @@
# -- 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
@@ -177,12 +167,12 @@
# 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,
@@ -219,7 +209,7 @@
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
@@ -344,11 +334,28 @@
}
breathe_default_project = "Zephyr"
+# Qualifiers to a function are causing Sphihx/Breathe to warn about
+# Error when parsing function declaration and more. This is a list
+# of strings that the parser additionally should accept as
+# attributes.
+cpp_id_attributes = ['__syscall', '__syscall_inline', '__deprecated',
+ '__may_alias', '__used', '__unused', '__weak',
+ '__DEPRECATED_MACRO', 'FUNC_NORETURN' ]
+
+
# docs_title is used in the breadcrumb title in the zephyr docs theme
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', '')}
@@ -367,3 +374,4 @@
def setup(app):
app.add_stylesheet("zephyr-custom.css")
+ app.add_javascript("zephyr-custom.js")
diff --git a/doc/images/Zephyr-Kite-logo.png b/doc/images/Zephyr-Kite-logo.png
new file mode 100644
index 0000000..d2ca719
--- /dev/null
+++ b/doc/images/Zephyr-Kite-logo.png
Binary files differ
diff --git a/doc/images/zp_favicon.png b/doc/images/zp_favicon.png
new file mode 100644
index 0000000..820bf44
--- /dev/null
+++ b/doc/images/zp_favicon.png
Binary files differ
diff --git a/doc/scripts/filter-doc-log.sh b/doc/scripts/filter-doc-log.sh
new file mode 100755
index 0000000..22d562e
--- /dev/null
+++ b/doc/scripts/filter-doc-log.sh
@@ -0,0 +1,40 @@
+#!/bin/bash
+
+# run the filter-known-issues.py script to remove "expected" warning
+# messages from the output of the document build process and write
+# the filtered output to stdout
+#
+# Only argument is the name of the log file saved by the build.
+
+KI_SCRIPT=${ZEPHYR_BASE}/scripts/filter-known-issues.py
+CONFIG_DIR=${ZEPHYR_BASE}/.known-issues/doc
+
+LOG_FILE=$1
+
+red='\E[31m'
+green='\e[32m'
+
+if [ -z "${LOG_FILE}" ]; then
+ echo "Error in $0: missing input parameter <logfile>"
+ exit 1
+fi
+
+if [ -s "${LOG_FILE}" ]; then
+ $KI_SCRIPT --config-dir ${CONFIG_DIR} ${LOG_FILE} > doc.warnings 2>&1
+ if [ -s doc.warnings ]; then
+ echo
+ echo -e "${red}New errors/warnings found, please fix them:"
+ echo -e "=============================================="
+ tput sgr0
+ echo
+ cat doc.warnings
+ echo
+ else
+ echo -e "${green}No new errors/warnings."
+ tput sgr0
+ fi
+
+else
+ echo "Error in $0: logfile \"${LOG_FILE}\" not found."
+ exit 1
+fi
diff --git a/doc/scripts/genrest/genrest.py b/doc/scripts/genrest/genrest.py
index bc08173..0688de5 100644
--- a/doc/scripts/genrest/genrest.py
+++ b/doc/scripts/genrest/genrest.py
@@ -47,7 +47,7 @@
config = open("%s/%s.rst" % (outdir, var), "w")
config.write(":orphan:\n\n")
config.write(".. title:: %s\n\n" %item.get_name())
- config.write(".. option:: CONFIG_%s:\n" %item.get_name())
+ config.write(".. option:: CONFIG_%s\n" %item.get_name())
config.write(".. _CONFIG_%s:\n" %item.get_name())
if text:
config.write("\n%s\n\n" %text)
diff --git a/doc/static/zephyr-custom.css b/doc/static/zephyr-custom.css
index e500380..635157e 100644
--- a/doc/static/zephyr-custom.css
+++ b/doc/static/zephyr-custom.css
@@ -1,4 +1,103 @@
-/* -- Extra CSS styles for Zephyr content ----------------------------------- */
+/* -- 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 {
@@ -9,3 +108,49 @@
th,td {
white-space: normal !important;
}
+
+/* dbk tweak for doxygen-generated API headings (for RTD theme) */
+.rst-content dl.group>dt, .rst-content dl.group>dd>p {
+ display:none !important;
+}
+.rst-content dl.group {
+ margin: 0 0 12px 0px;
+}
+.rst-content dl.group>dd {
+ margin-left: 0 !important;
+}
+.rst-content p.breathe-sectiondef-title {
+ text-decoration: underline; /* dbk for API sub-headings */
+ font-size: 1.25rem;
+ font-weight: bold;
+ margin-bottom: 12px;
+}
+.rst-content div.breathe-sectiondef {
+ padding-left: 0 !important;
+}
+
+/* tweak display of option tables to make first column wider */
+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;
+}
diff --git a/doc/static/zephyr-custom.js b/doc/static/zephyr-custom.js
new file mode 100644
index 0000000..d7389f9
--- /dev/null
+++ b/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");
+});
diff --git a/doc/zephyr.doxyfile b/doc/zephyr.doxyfile
index a993b8c..36bf8f1 100644
--- a/doc/zephyr.doxyfile
+++ b/doc/zephyr.doxyfile
@@ -116,7 +116,11 @@
EXCLUDE =
EXCLUDE_SYMLINKS =
EXCLUDE_PATTERNS =
-EXCLUDE_SYMBOLS =
+
+# Hide internal names (starting with an underscore, and doxygen-generated names
+# for nested unnamed unions that don't generate meaningful sphinx output anyway.
+EXCLUDE_SYMBOLS = _* *.__unnamed__
+
EXAMPLE_PATH =
EXAMPLE_PATTERNS =
EXAMPLE_RECURSIVE = YES
@@ -279,9 +283,14 @@
"CONFIG_DEVICE_POWER_MANAGEMENT=y" \
"CONFIG_BT_SMP=y" \
"CONFIG_BT_BREDR=y" \
- "__deprecated=" \
- "__printf_like(x, y)=" \
- "__attribute(x)__="
+ "NET_MGMT_DEFINE_REQUEST_HANDLER(x)=" \
+ "__deprecated=" \
+ "__packed=" \
+ "__aligned(x)=" \
+ "__printf_like(x, y)=" \
+ "__attribute__(x)=" \
+ "__syscall=" \
+ "__syscall_inline="
EXPAND_AS_DEFINED =
SKIP_FUNCTION_MACROS = NO
#---------------------------------------------------------------------------
diff --git a/scripts/filter-known-issues.py b/scripts/filter-known-issues.py
index f09bb8a..98d551e 100755
--- a/scripts/filter-known-issues.py
+++ b/scripts/filter-known-issues.py
@@ -185,6 +185,8 @@
warnings.write(data)
for filename in args.FILENAMEs:
+ if os.stat(filename).st_size == 0:
+ continue # skip empty log files
try:
with open(filename, "r+b") as f:
logging.info("%s: filtering", filename)
