doc: fix doxygen INPUT path; brand html output

Clean up the INPUT paths for doxygen scanning: - directory scans include sub-directories so no need to include them explicitly - remove excluded (legacy) includes that no longer exist Sync directory changes in the CMakeLists.txt (as noted in the comments) Add content to the home page of the doxygen-generated HTML, and add a Zephyr branding theme. Signed-off-by: David B. Kinder <[email protected]> Fixes: zephyrproject-rtos#6773
mlaz · Jun 27, 2019 · b30b52a · b30b52a
1 parent 7a73bb7
commit b30b52a
Show file tree

Hide file tree

Showing 7 changed files with 157 additions and 21 deletions.
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
@@ -131,6 +131,7 @@ add_custom_target(
 file(GLOB_RECURSE  DOXY_SOURCES
   ${ZEPHYR_BASE}/include/*.[c,h,S]
   ${ZEPHYR_BASE}/lib/libc/*.[c,h,S]
+  ${ZEPHYR_BASE}/subsys/testsuite/ztest/include/*.[h,c,S]
   ${ZEPHYR_BASE}/tests/*.[h,c,S]
   )
 # For debug. Also find generated list in doc/_build/(build.ninja|CMakeFiles/)

diff --git a/doc/custom-doxygen/customdoxygen.css b/doc/custom-doxygen/customdoxygen.css
@@ -0,0 +1,36 @@
+/* Custom CSS for Doxygen-generated HTML
+ * Copyright (c) 2015 Intel Corporation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+code {
+  font-family: Monaco,Menlo,Consolas,"Courier New",monospace;
+  background-color: #D8D8D8;
+  padding: 0 0.25em 0 0.25em;
+}
+
+pre.fragment {
+  display: block;
+  font-family: Monaco,Menlo,Consolas,"Courier New",monospace;
+  padding: 1rem;
+  word-break: break-all;
+  word-wrap: break-word;
+  white-space: pre;
+  background-color: #D8D8D8;
+}
+
+#projectlogo
+{
+  vertical-align: middle;
+}
+
+#projectname
+{
+  font: 200% Tahoma, Arial,sans-serif;
+  color: #3D578C;
+}
+
+#projectbrief
+{
+  color: #3D578C;
+}
diff --git a/doc/custom-doxygen/footer.html b/doc/custom-doxygen/footer.html
@@ -0,0 +1,21 @@
+<!-- HTML footer for doxygen 1.8.13-->
+<!-- start footer part -->
+<!--BEGIN GENERATE_TREEVIEW-->
+<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
+  <ul>
+    $navpath
+    <li class="footer">$generatedby
+    <a href="http://www.doxygen.org/index.html">
+    <img class="footer" src="$relpath^doxygen.png" alt="doxygen"/></a> $doxygenversion </li>
+  </ul>
+</div>
+<!--END GENERATE_TREEVIEW-->
+<!--BEGIN !GENERATE_TREEVIEW-->
+<hr class="footer"/><address class="footer"><small>
+$generatedby &#160;<a href="http://www.doxygen.org/index.html">
+<img class="footer" src="$relpath^doxygen.png" alt="doxygen"/>
+</a> $doxygenversion
+</small></address>
+<!--END !GENERATE_TREEVIEW-->
+</body>
+</html>
diff --git a/doc/custom-doxygen/header.html b/doc/custom-doxygen/header.html
@@ -0,0 +1,57 @@
+<!-- HTML header for doxygen 1.8.13-->
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
+<meta http-equiv="X-UA-Compatible" content="IE=9"/>
+<meta name="generator" content="Doxygen $doxygenversion"/>
+<meta name="viewport" content="width=device-width, initial-scale=1"/>
+<!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->
+<!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME-->
+<link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>
+<script type="text/javascript" src="$relpath^jquery.js"></script>
+<script type="text/javascript" src="$relpath^dynsections.js"></script>
+$treeview
+$search
+$mathjax
+<link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
+$extrastylesheet
+</head>
+<body>
+<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
+
+<!--BEGIN TITLEAREA-->
+<div id="titlearea">
+<table cellspacing="0" cellpadding="0">
+ <tbody>
+ <tr style="height: 56px;">
+  <!--BEGIN PROJECT_LOGO-->
+  <td id="projectlogo"><a href="https://docs.zephyrproject.org/latest/"
+     target="_blank"><img alt="Logo" src="$relpath^$projectlogo"/></a></td>
+  <!--END PROJECT_LOGO-->
+  <!--BEGIN PROJECT_NAME-->
+  <td id="projectalign" style="padding-left: 1em;">
+   <div id="projectname">$projectname
+   <!--BEGIN PROJECT_NUMBER-->&#160;<span id="projectnumber">$projectnumber</span><!--END PROJECT_NUMBER-->
+   </div>
+   <!--BEGIN PROJECT_BRIEF--><div id="projectbrief">$projectbrief</div><!--END PROJECT_BRIEF-->
+  </td>
+  <!--END PROJECT_NAME-->
+  <!--BEGIN !PROJECT_NAME-->
+   <!--BEGIN PROJECT_BRIEF-->
+    <td style="padding-left: 0.5em;">
+    <div id="projectbrief">$projectbrief</div>
+    </td>
+   <!--END PROJECT_BRIEF-->
+  <!--END !PROJECT_NAME-->
+  <!--BEGIN DISABLE_INDEX-->
+   <!--BEGIN SEARCHENGINE-->
+   <td>$searchbox</td>
+   <!--END SEARCHENGINE-->
+  <!--END DISABLE_INDEX-->
+ </tr>
+ </tbody>
+</table>
+</div>
+<!--END TITLEAREA-->
+<!-- end header part -->
diff --git a/doc/custom-doxygen/mainpage.md b/doc/custom-doxygen/mainpage.md
@@ -0,0 +1,29 @@
+# API Documentation   {#index}
+
+## Introduction
+
+The Zephyr OS is a small-footprint kernel designed for use on
+resource-constrained and embedded systems: from simple embedded
+environmental sensors and LED wearables to sophisticated embedded
+controllers, smart watches, and IoT wireless applications.
+
+See the [zephyrproject.org](https://zephyrproject.org) site for more
+information about the project and becoming a member, and this [summary
+of Zephyr resources](https://docs.zephyrproject.org/latest/introduction/index.html#resources)
+to help you find your way around the project.
+
+## Supported Boards
+
+The Zephyr kernel supports multiple architectures, including ARM
+Cortex-M, Intel x86, ARC, NIOS II, Tensilica Xtensa, and RISC-V 32.  For
+details, see the [latest supported boards
+documentation](https://docs.zephyrproject.org/latest/boards/index.html).
+
+## Licensing
+
+Zephyr is permissively licensed using the Apache 2.0 license (as found
+in the [project's GitHub LICENSE
+file](https://github.com/zephyrproject-rtos/zephyr/blob/master/LICENSE).
+There are some imported or reused components of the Zephyr project that
+use other licensing, as described in [Licensing of Zephyr Project
+components](https://docs.zephyrproject.org/latest/LICENSING.html#zephyr-licensing).
diff --git a/doc/images/Zephyr-Kite-small.png b/doc/images/Zephyr-Kite-small.png
diff --git a/doc/zephyr.doxyfile.in b/doc/zephyr.doxyfile.in
@@ -44,14 +44,14 @@ PROJECT_NUMBER         =
 # for a project that appears at the top of each page and should give viewer a
 # quick idea about the purpose of the project. Keep the description short.
 
-PROJECT_BRIEF          =
+PROJECT_BRIEF          = "A Scalable Open Source RTOS for IoT Embedded Devices"
 
 # With the PROJECT_LOGO tag one can specify a logo or an icon that is included
 # in the documentation. The maximum height of the logo should not exceed 55
 # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy
 # the logo to the output directory.
 
-PROJECT_LOGO           =
+PROJECT_LOGO           = "images/Zephyr-Kite-small.png"
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path
 # into which the generated documentation will be written. If a relative path is
@@ -748,16 +748,9 @@ WARN_LOGFILE           =
 
 # This MUST be kept in sync with DOXY_SOURCES in doc/CMakeLists.txt
 # for incremental (and faster) builds to work correctly.
-INPUT                  = @ZEPHYR_BASE@/include/ \
-                         @ZEPHYR_BASE@/include/misc/ \
-                         @ZEPHYR_BASE@/include/arch/x86/ \
-                         @ZEPHYR_BASE@/include/arch/arc/ \
-                         @ZEPHYR_BASE@/include/arch/arc/v2 \
-                         @ZEPHYR_BASE@/include/arch/arm/ \
-                         @ZEPHYR_BASE@/include/arch/arm/cortex_m \
-                         @ZEPHYR_BASE@/include/arch/nios2/ \
+INPUT                  = custom-doxygen/mainpage.md \
+                         @ZEPHYR_BASE@/include/ \
                          @ZEPHYR_BASE@/lib/libc/minimal/include/ \
-                         @ZEPHYR_BASE@/include/net/dns_resolve.h \
 			 @ZEPHYR_BASE@/subsys/testsuite/ztest/include/ \
 			 @ZEPHYR_BASE@/tests/kernel/
 
@@ -788,7 +781,8 @@ INPUT_ENCODING         = UTF-8
 # for incremental (and faster) builds to work correctly.
 FILE_PATTERNS          = "*.c" \
                          "*.h" \
-                         "*.S"
+                         "*.S" \
+                         "*.md"
 
 # The RECURSIVE tag can be used to specify whether or not subdirectories should
 # be searched for input files as well.
@@ -803,9 +797,7 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                = @ZEPHYR_BASE@/include/spi_legacy.h \
-                         @ZEPHYR_BASE@/include/net/http_legacy.h \
-                         @ZEPHYR_BASE@/include/cmsis_rtos_v1/cmsis_os.h \
+EXCLUDE                = @ZEPHYR_BASE@/include/cmsis_rtos_v1/cmsis_os.h \
                          @ZEPHYR_BASE@/include/cmsis_rtos_v2/cmsis_os2.h \
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
@@ -917,7 +909,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE = YES
+USE_MDFILE_AS_MAINPAGE = "mainpage.md"
 
 #---------------------------------------------------------------------------
 # Configuration options related to source browsing
@@ -1073,7 +1065,7 @@ HTML_FILE_EXTENSION    = .html
 # of the possible markers and block names see the documentation.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_HEADER            =
+HTML_HEADER            = custom-doxygen/header.html
 
 # The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each
 # generated HTML page. If the tag is left blank doxygen will generate a standard
@@ -1108,7 +1100,7 @@ HTML_STYLESHEET        =
 # list). For an example see the documentation.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_EXTRA_STYLESHEET  =
+HTML_EXTRA_STYLESHEET  = custom-doxygen/customdoxygen.css
 
 # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
 # other source files which should be copied to the HTML output directory. Note
@@ -1129,15 +1121,15 @@ HTML_EXTRA_FILES       =
 # Minimum value: 0, maximum value: 359, default value: 220.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_COLORSTYLE_HUE    = 220
+HTML_COLORSTYLE_HUE    =
 
 # The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of the colors
 # in the HTML output. For a value of 0 the output will use grayscales only. A
 # value of 255 will produce the most vivid colors.
 # Minimum value: 0, maximum value: 255, default value: 100.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_COLORSTYLE_SAT    = 100
+HTML_COLORSTYLE_SAT    =
 
 # The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to the
 # luminance component of the colors in the HTML output. Values below 100
@@ -1148,7 +1140,7 @@ HTML_COLORSTYLE_SAT    = 100
 # Minimum value: 40, maximum value: 240, default value: 80.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_COLORSTYLE_GAMMA  = 80
+HTML_COLORSTYLE_GAMMA  =
 
 # If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML
 # page will contain the date and time when the page was generated. Setting this