From b30b52abd5214c03089be8d13ff4082d71424494 Mon Sep 17 00:00:00 2001 From: "David B. Kinder" Date: Tue, 25 Jun 2019 15:54:19 -0700 Subject: [PATCH] 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 Fixes: #6773 --- doc/CMakeLists.txt | 1 + doc/custom-doxygen/customdoxygen.css | 36 +++++++++++++++++ doc/custom-doxygen/footer.html | 21 ++++++++++ doc/custom-doxygen/header.html | 57 +++++++++++++++++++++++++++ doc/custom-doxygen/mainpage.md | 29 ++++++++++++++ doc/images/Zephyr-Kite-small.png | Bin 0 -> 4785 bytes doc/zephyr.doxyfile.in | 34 ++++++---------- 7 files changed, 157 insertions(+), 21 deletions(-) create mode 100644 doc/custom-doxygen/customdoxygen.css create mode 100644 doc/custom-doxygen/footer.html create mode 100644 doc/custom-doxygen/header.html create mode 100644 doc/custom-doxygen/mainpage.md create mode 100644 doc/images/Zephyr-Kite-small.png diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 9f028d465a8..8defe83c071 100644 --- 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 new file mode 100644 index 00000000000..4735e41cf5d --- /dev/null +++ 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 new file mode 100644 index 00000000000..a24bf2b9b47 --- /dev/null +++ b/doc/custom-doxygen/footer.html @@ -0,0 +1,21 @@ + + + + + + +
+$generatedby   +doxygen + $doxygenversion +
+ + + diff --git a/doc/custom-doxygen/header.html b/doc/custom-doxygen/header.html new file mode 100644 index 00000000000..c6b0c853e69 --- /dev/null +++ b/doc/custom-doxygen/header.html @@ -0,0 +1,57 @@ + + + + + + + + +$projectname: $title +$title + + + +$treeview +$search +$mathjax + +$extrastylesheet + + +
+ + +
+ + + + + + + + + + + + + + + + + + + + + +
+
$projectname +  $projectnumber +
+
$projectbrief
+ 		+
$projectbrief
+ 		$searchbox
+
+ + diff --git a/doc/custom-doxygen/mainpage.md b/doc/custom-doxygen/mainpage.md new file mode 100644 index 00000000000..f0b5638f74d --- /dev/null +++ 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 new file mode 100644 index 0000000000000000000000000000000000000000..5acdaa79ff467299bb5d3f075c8fded389735df2 GIT binary patch literal 4785 zcmbVQc{tQ--=9c!B1;`%nncQ&8N+ND(va+wQZZ>(#xgU_3^RnZ*hZanER&_AQX&)~ zAv-B+wp5l=)({~H=^1VBdEVd-@8`SR-#>m)j`o(aQol(7003F5 zedhaxZ#UtCl2|AFXYx~(gfB_vz9Vb^K!5A%vxb*$>JI>jEz+D1a}L|tVn_^MeFB+5 zr0DZ}nL;!GU~I}`5=h<@4v?@#-=J1pEf!cw<3ks|JCG?HqwP28#kT z(no+vFhe6C60HwIzzxx8J)i*;hJrv*5EvW`LtqS{7y|>~j~_^AjYXzn_M7khVM{o} zf;>4KCI$lGa=H3kxITmB0fC{>Xb98*VqgFkBEakbI)}gm)7e{pGMH1?Bo>Xyp)u&d zRYn4l;m5&(gi61=;LH3)OK1NGlQ3Wq9)Ssg=|fjt`UWJEe&LvYET3=2$s`EHhvG}2 zbJ#*G>=%~l$>1>9o{axM{cHQ*3RYN9l2>&OTOu|qZ zEMJ1qXPPg;g92gFJwU);k;LE_J`9%7uuvWRuj^JgoFj`trTGXq*!wN_0Ie)=2pAe6 z6t55aCfCjmV?}3k2y_y~${Y(4#z&tgRiTv}tIfLZ4S_P};zh4M4gCykmA9+xyA(Tv|5Wz+S3IS{YH>83I2w~kDP*DbO z12lzzpb~$wIk0HLJ4x{QE92k|E~U@W%IkNzg7R&!u@}${}CLLCxPxk z5w=2Iz{#46JeRfZ8k4>q63L+=A4rczK^?{#Rx|gmP-~4TY;TmPdm*Itb zoJCGQl$87kkCeYQFX|3hVne0 zR)4p`khg3qJY@Itw@&(tjf270O)iRVGgHE(1r}_S`#3WXDYY@ZG~3#?gO^v?uQkT& z((Tf1*6s2toP0i+(4A1^YNB~0J@qnQ8Qr@*WL)!9;6Rk!X)cZ@azCt1%)-rMe$%eY znGK@uWlyGz=f6PXB6=`9D%MAEnhjp>T9l2?@0|%DDm$o)-4Dv|tIz+~XDa$g4HcR} zOb)#TClo12bSMT7I@nizrY-c6s;+#29$gbFdoQIJ(L~MSvmcQ2U!h8}t1STLa7hii zym2Lu?k7<>KDQHn$B;0cVVgxVW#3Gl(|R?t*0Ktt_W25ot%v$}y+Cf^y`o#Pg~_R^ zcOw_0P7WN4-*nrc+g3Upzg08q!K>`kQ*kxA8VMRi`$oCZa)G#RfMmc(>m;9w1Ryid zsgUJEMF$3QKyk@WG)=Q-o^O1AV2UF%d@#pFsq^DvDM&r5-?htU!+31I=(1(N?)d;1 zTA-{MufI-zteUMmCs$`O(Ch8Kc_ytxx}PV;_B}LrpJXpTe~WTIjnLaSHrOVlDZ9SLC#U)PDvM}MgZ_Ct0EE`QF9(Mo!xEd5w(qaBYL6e)NXoM#$2 zoqbEJd|Qbap1TpRqkFp3{#k?NA@z~{FMSQdAy3sUG8)waX3C>WXZs%Q;+(|4G1ua+ z?bkvT1hRr6ZDz4~rst>c>Q5a7IJ;isdWTDIyuH@?_UTg`JaN1(st+^ai?)HQpo4QN zCQ?SR5m|$*Lw`uvX#9X=QEUZ^ZlpKN_{Cw4z$kcZ%vUO z41=_Ia&AVXt%-T$s{1?Gx`6CaaTnQ=r@}5vF&$(WO*F&@oFZaz( z726y%-}idQ3*?2HdR&23J@-qS`mXeZMno+j=}=aS`?jmOQK#-*9Ii=O7@0kaVa43+ z@%ixj(Nj5k#~eqTd4#32p5p~ZT=*2a*^?WdO_xy0)v4$t;!#-Zycg?p!s&V0_#R&jLM`-*RL%pvrO z?`T!x_zRRuyP#She4eZ+#abinRP9z4)YQxUv?WOSeseZ0Fd^@8v>X4AV<&n%;@WBy zc25eHhcCJ3rt zyz9*Ej{3zN5htHt+VJ^w{Skhv?b$2V|JpiDhO=RWU9ew<+5ji;=2J zw%h2$7|N~}@xS$Pph^{H4#j=vO1l*X8N+CPd)J_rDMlY^4m_tNUXenlqz1x*3RTh${Yjg zl{$C5i_e5%P3U7j&+HZVZkopFYZ;--P;dJ*WfFB&{XV@p=#v(Qlo9{^PSREh|ALYT zmz0LZ0vTsmTBXEMwCgRzA^5Ep%P&o;1utpa7VRq9Kctje;kc1Ex$lM4u(ItM> z>(Xsd7LIOl&Ee0p$^57@0(j(sE4y3>Co*-9xrYW$pz^z|56M-kUaC(VZXWcA#`R^2NkFRt&-b`eWER)@7Tc`$rU>UGSLC999~w_izS% z<|8LVvSE7m*V?kP!n*dP9pAWJDj%Kz0M?!4!6~YP;2~krk!1`b$DmkZ(BRR_i>Yh@1Xse(#o!E`zv^@qntPK#y;YC zfpDy5M`*pY^6zz9G&5AK@zTaoTigxjRMsYY24LUktCnWzAb@_6>!wKhjX68@gYG z&$hm_m5$z1M)aE)T8D6IP?l}zTUi+pVLq*Fc$MTdd>E4y6vCtUt>tbWXR>;RE?s8sB#r%1eibjh$OeEK z9Qv8NpEF(ku1$&2U9BhY9nWyP*!xjhmSkKhA10UaBx_SgY{gdqL?n9BbJ4#7vL^M} z+_Y-pi|$&i_b25ur9ja6RK{@(ROdb4T4ZLoAwd$c-#1k zQQ~IJqpv$78=l#Hz*R2zR%?h~Z2_b{UBMQrHax($EvGlOpUP7o01c?hoTzrXQlPYG ze4hI@+9~Nu>F#qqSqfI|CkCz>o0+KNp5GeE_%NgaQMy&$O{Quon(FY9tL;PcH@%4M znJva%s#gQZP2Z7OyzROaS5R@*Eig1b>T=>G?MUXxD=Ak9aDtzr?>{pkrBE0Lu;dNgG`I8FARm32+ zLpLzVjv5XbP3eL@HujESUi55^&I)w;WW`dxSO1}N*l=nSERcRl)N&>+JowGNQ|#sV zb@2`7?j0v8G+!UjEAl4lm@LD0OBnMFyv{sWM5^fJyKK$OS8=S`<8}5;xFQ%+^~yK} zFTNaI!9*0CTEBg&rn1JaiBEg~II#9urmeQaAbacDd{quuW|p+ODW6Fx?L87gnkg8L;k{1X*=KBu z#EX|AiavtEKcH10k6M~8)J9ylK)x9{cg=HuD>zDTZ=?!7sdwkI=cXdd?~?F+VnI45 z8N0GR1E-H14B0QUkhVN_tY9=(Z8}Q&!sO$2$9m2H=b|fILd#uu?0+M9 z0v9#@`=0U$zr~T8qNz`ka+?g_rYFlj?764f`~Fg3PnS>d&grEi z2_~Y;dJ4e=8K|6?6~Ju*z$Y~t5)={q*$T!Q)1um?1~thA$pIVJCJlv#UC)f4 zE|EuyOjFi{Xe{6cijaV>V0zVy3#q>~BzPkE-R7 literal 0 HcmV?d00001 diff --git a/doc/zephyr.doxyfile.in b/doc/zephyr.doxyfile.in index c747e7fd8e7..7433a8e78e6 100644 --- 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,7 +1121,7 @@ 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 @@ -1137,7 +1129,7 @@ HTML_COLORSTYLE_HUE = 220 # 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