From 9754e3d0231d56aeb5495a580d6059cc1d2f1872 Mon Sep 17 00:00:00 2001 From: Vivien Nicolas Date: Fri, 18 Sep 2020 19:53:58 +0200 Subject: [PATCH] Get Doxygen documentation to be independent of the build system (#2703) --- .gitignore | 3 + Makefile.am | 19 --- README.md | 49 +++--- configure.ac | 10 -- docs/ChipDoxygenLayout.xml | 61 +++++--- docs/{Doxyfile.in => Doxyfile} | 199 ++++++++++-------------- docs/Makefile.am | 118 -------------- scripts/helpers/doxygen-format-check.sh | 35 ----- scripts/helpers/doxygen.sh | 71 +++++++++ 9 files changed, 222 insertions(+), 343 deletions(-) rename docs/{Doxyfile.in => Doxyfile} (95%) delete mode 100644 docs/Makefile.am delete mode 100755 scripts/helpers/doxygen-format-check.sh create mode 100755 scripts/helpers/doxygen.sh diff --git a/.gitignore b/.gitignore index 644be90c86cda2..4bbf7fe28d4974 100644 --- a/.gitignore +++ b/.gitignore @@ -62,3 +62,6 @@ TAGS # Python bytecodes __pycache__ *.pyc + +# Doxygen outputs +docs/html diff --git a/Makefile.am b/Makefile.am index cf3079b0b99c61..59b61488dd750b 100644 --- a/Makefile.am +++ b/Makefile.am @@ -34,7 +34,6 @@ SUBDIRS = \ examples \ third_party \ src \ - docs \ $(NULL) PRETTY_SUBDIRS = \ @@ -215,24 +214,6 @@ dist-hook: $(distdir)/.dist-version distclean-local: $(MAKE) -C $(srcdir) -f Makefile-bootstrap clean-repos -# -# Top-level convenience target for making documentation. -# - -.PHONY: doc -doc: $(BUILT_SOURCES) - $(MAKE) -C docs $(@) - -# -# Top-level convenience target for making a documentation-only -# distribution whose results appear at the top level of the build tree -# in the same fashion that the distribution would be for 'make dist'. -# - -.PHONY: docdist -docdist: $(BUILT_SOURCES) - $(MAKE) -C docs docdistdir=$(abs_builddir) $(@) - # # Top-level convenience target for making a tools-only distribution # whose resuls appear at the top level of the build tree in the same diff --git a/README.md b/README.md index 5e366584af4068..829deaa925848d 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Connected Home over IP +# Connected Home over IP {#mainpage} ![Main](https://github.com/project-chip/connectedhomeip/workflows/Builds/badge.svg) ![Examples](https://github.com/project-chip/connectedhomeip/workflows/Examples/badge.svg) @@ -137,39 +137,38 @@ scalability. # How to Contribute We welcome your contributions to Project Connected Home over IP. Read our -contribution guidelines -[here](https://github.com/project-chip/connectedhomeip/blob/master/CONTRIBUTING.md). +contribution guidelines [here](./CONTRIBUTING.md). # Building and Developing in Project Instructions about how to build Project Connected Home over IP can be found -[here](./docs/README.md#building-and-developing). +[here](./docs/README.md). # Directory Structure The Connected Home over IP repository is structured as follows: -| File / Folder | Contents | -| ---------------------- | -------------------------------------------------------------------------------------------------------------------- | -| `.default-version` | Default Project CHIP version if none is available via source code control tags, `.dist-version`, or `.local-version` | -| `bootstrap` | GNU autotools bootstrap script for the Project CHIP build system | -| `bootstrap-configure` | Convenience script that will bootstrap the Project CHIP build system, via `bootstrap`, and invoke `configure` | -| `build/` | Build system support content and build output directories | -| `BUILDING.md` | More detailed information on configuring and building Project CHIP for different targets | -| `CODE_OF_CONDUCT.md` | Code of Conduct for Project CHIP, and contributions to it | -| `CONTRIBUTING.md` | Guidelines for contributing to Project CHIP | -| `CONTRIBUTORS.md` | Contributors to Project CHIP | -| `docs/` | Documentation | -| `examples/` | Example firmware applications that demonstrate use of Project CHIP technology | -| `integrations/` | Third party integrations related to this project | -| `integrations/docker/` | Docker scripts and Dockerfiles | -| `LICENSE` | Project CHIP [License file](./LICENSE) (Apache 2.0) | -| `Makefile-Android` | Convenience makefile for building Project CHIP against Android | -| `Makefile-Standalone` | Convenience makefile for building Project CHIP as a standalone package on desktop and server systems | -| `README.md` | This file | -| `src/` | Implementation of Project CHIP | -| `third_party/` | Third-party code used by Project CHIP | -| `tools/` | Tools needed to work with the Project CHIP repo | +| File / Folder | Contents | +| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | +| `.default-version` | Default Project CHIP version if none is available via source code control tags, `.dist-version`, or `.local-version` | +| `bootstrap` | GNU autotools bootstrap script for the Project CHIP build system | +| `bootstrap-configure` | Convenience script that will bootstrap the Project CHIP build system, via `bootstrap`, and invoke `configure` | +| `build/` | Build system support content and build output directories | +| [BUILDING.md](./docs/BUILDING.md) | More detailed information on configuring and building Project CHIP for different targets | +| `CODE_OF_CONDUCT.md` | Code of Conduct for Project CHIP, and contributions to it | +| [CONTRIBUTING.md](./CONTRIBUTING.md) | Guidelines for contributing to Project CHIP | +| `CONTRIBUTORS.md` | Contributors to Project CHIP | +| `docs/` | Documentation | +| `examples/` | Example firmware applications that demonstrate use of Project CHIP technology | +| `integrations/` | Third party integrations related to this project | +| `integrations/docker/` | Docker scripts and Dockerfiles | +| `LICENSE` | Project CHIP [License file](./LICENSE) (Apache 2.0) | +| `Makefile-Android` | Convenience makefile for building Project CHIP against Android | +| `Makefile-Standalone` | Convenience makefile for building Project CHIP as a standalone package on desktop and server systems | +| `README.md` | This file | +| `src/` | Implementation of Project CHIP | +| `third_party/` | Third-party code used by Project CHIP | +| `tools/` | Tools needed to work with the Project CHIP repo | # License diff --git a/configure.ac b/configure.ac index 3de9a861522efa..db372fe9c49464 100644 --- a/configure.ac +++ b/configure.ac @@ -896,14 +896,6 @@ AC_DEFINE_UNQUOTED([CHIP_ENABLE_CHIPOBLE_TEST],[${CHIP_ENABLE_CHIPOBLE_TEST}],[D # Documentation # -# Determine whether or not documentation (via Doxygen) should be built -# or not, with 'auto' as the default and establish a default support -# value for GraphViz 'dot' support. - -NL_ENABLE_DOCS([auto],[NO]) - -AM_CONDITIONAL(CHIP_BUILD_DOCS, [test "${nl_cv_build_docs}" = "yes"]) - # # Network Technology Layer # @@ -2552,7 +2544,6 @@ fi # AC_CONFIG_FILES([ Makefile -docs/Makefile examples/Makefile third_party/Makefile third_party/lwip/Makefile @@ -2650,7 +2641,6 @@ AC_MSG_NOTICE([ Python extension directory : ${pyexecdir:--} Verhoeff support : ${enable_verhoeff} Pairing code decoding support : ${enable_pairing_code_decoding} - Documentation support : ${nl_cv_build_docs} Clang-format : ${CLANG_FORMAT:--} Doxygen : ${DOXYGEN:--} GraphViz dot : ${DOT:--} diff --git a/docs/ChipDoxygenLayout.xml b/docs/ChipDoxygenLayout.xml index 0f264e01d6f0d0..68f3f9e3e703b6 100644 --- a/docs/ChipDoxygenLayout.xml +++ b/docs/ChipDoxygenLayout.xml @@ -1,39 +1,40 @@ - + - - - - - - - - - - - - - - - - - + + + + + + + + + + - + + + + + + + + + + - + - @@ -99,8 +100,13 @@ + + + + + @@ -110,6 +116,8 @@ + + @@ -125,11 +133,16 @@ + + + + + @@ -140,6 +153,8 @@ + + @@ -159,6 +174,8 @@ + + @@ -178,6 +195,8 @@ + + diff --git a/docs/Doxyfile.in b/docs/Doxyfile similarity index 95% rename from docs/Doxyfile.in rename to docs/Doxyfile index e21e90a50be4ae..e6118566384476 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile @@ -1,42 +1,17 @@ -# Doxyfile 1.8.16 -# -# Copyright (c) 2020 Project CHIP Authors -# Copyright (c) 2018 Google LLC -# Copyright (c) 2014-2018 Nest Labs, Inc. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -# +# Doxyfile 1.8.18 +# This file describes the settings to be used by the documentation system +# doxygen (www.doxygen.org) for a project. # -# Description: -# This file describes the settings to be used by the -# documentation system # doxygen (www.doxygen.org) for Chip. -# -# This was initially autogenerated 'doxywizard' and then hand-tuned. -# -# All text after a hash (#) is considered a comment and will be -# ignored. -# -# The format is: -# -# TAG = value [value, ...] -# -# For lists items can also be appended using: -# -# TAG += value [value, ...] -# -# Values that contain spaces should be placed between quotes (" ") +# All text after a double hash (##) is considered a comment and is placed in +# front of the TAG it is preceding. # +# All text after a single hash (#) is considered a comment and will be ignored. +# The format is: +# TAG = value [value, ...] +# For lists, items can also be appended using: +# TAG += value [value, ...] +# Values that contain spaces should be placed between quotes (\" \"). #--------------------------------------------------------------------------- # Project related configuration options @@ -57,33 +32,33 @@ DOXYFILE_ENCODING = UTF-8 # title of most generated pages and in a few other places. # The default value is: My Project. -PROJECT_NAME = @PACKAGE_NAME@ +PROJECT_NAME = $(CHIP_NAME) # The PROJECT_NUMBER tag can be used to enter a project or revision number. This # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = @PACKAGE_VERSION@ +PROJECT_NUMBER = $(CHIP_VERSION) # Using the PROJECT_BRIEF tag one can provide an optional one line description # 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 CHIP is a home area network (HAN) application protocol stack designed to enable asynchronous, symmetric, device-to-device, device-to-service and service-to-device networking among IoT ecosystem devices for the purposes of both control- and data-path messaging. For specific network media in the HAN, CHIP enables wireless, low-power, battery-friendly communication by leveraging appropriate, standards-based technologies such as Wi-Fi, 802.15.4, 6LoWPAN, IP, TCP and UDP." +PROJECT_BRIEF = # 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 = @abs_srcdir@/images/logo.svg +PROJECT_LOGO = docs/images/logo.svg # 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 # entered, it will be relative to the location where doxygen was started. If # left blank the current directory will be used. -OUTPUT_DIRECTORY = @abs_builddir@ +OUTPUT_DIRECTORY = docs # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub- # directories (in 2 levels) under the output directory of each output format and @@ -195,8 +170,7 @@ FULL_PATH_NAMES = YES # will be relative from the directory where doxygen is started. # This tag requires that the tag FULL_PATH_NAMES is set to YES. -STRIP_FROM_PATH = @abs_top_srcdir@ \ - @abs_top_builddir@ +STRIP_FROM_PATH = src # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the # path mentioned in the documentation of a class, which tells the reader which @@ -205,7 +179,7 @@ STRIP_FROM_PATH = @abs_top_srcdir@ \ # specify the list of include paths that are normally passed to the compiler # using the -I flag. -STRIP_FROM_INC_PATH = @abs_top_srcdir@ +STRIP_FROM_INC_PATH = src # If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but # less readable) file names. This can be useful is your file systems doesn't @@ -289,12 +263,6 @@ TAB_SIZE = 4 ALIASES = -# This tag can be used to specify a number of word-keyword mappings (TCL only). -# A mapping has the form "name=value". For example adding "class=itcl::class" -# will allow you to use the command class in the itcl::class meaning. - -TCL_SUBST = - # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources # only. Doxygen will then generate output that is more tailored for C. For # instance, some of the names that are used will be different. The list of all @@ -335,14 +303,14 @@ OPTIMIZE_OUTPUT_SLICE = NO # parses. With this tag you can assign which parser to use for a given # extension. Doxygen has a built-in mapping, but you can override or extend it # using this tag. The format is ext=language, where ext is a file extension, and -# language is one of the parsers supported by doxygen: IDL, Java, Javascript, -# Csharp (C#), C, C++, D, PHP, md (Markdown), Objective-C, Python, Slice, +# language is one of the parsers supported by doxygen: IDL, Java, JavaScript, +# Csharp (C#), C, C++, D, PHP, md (Markdown), Objective-C, Python, Slice, VHDL, # Fortran (fixed format Fortran: FortranFixed, free formatted Fortran: # FortranFree, unknown formatted Fortran: Fortran. In the later case the parser # tries to guess whether the code is fixed or free formatted code, this is the -# default for Fortran type files), VHDL, tcl. For instance to make doxygen treat -# .inc files as Fortran files (default is PHP), and .f files as C (default is -# Fortran), use: inc=Fortran f=C. +# default for Fortran type files). For instance to make doxygen treat .inc files +# as Fortran files (default is PHP), and .f files as C (default is Fortran), +# use: inc=Fortran f=C. # # Note: For files without extension you can use no_extension as a placeholder. # @@ -493,7 +461,7 @@ LOOKUP_CACHE_SIZE = 0 # normally produced when WARNINGS is set to YES. # The default value is: NO. -EXTRACT_ALL = NO +EXTRACT_ALL = YES # If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will # be included in the documentation. @@ -561,8 +529,8 @@ HIDE_UNDOC_MEMBERS = NO HIDE_UNDOC_CLASSES = NO # If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend -# (class|struct|union) declarations. If set to NO, these declarations will be -# included in the documentation. +# declarations. If set to NO, these declarations will be included in the +# documentation. # The default value is: NO. HIDE_FRIEND_COMPOUNDS = NO @@ -767,7 +735,7 @@ FILE_VERSION_FILTER = # DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE # tag is left empty. -LAYOUT_FILE = ChipDoxygenLayout.xml +LAYOUT_FILE = docs/ChipDoxygenLayout.xml # The CITE_BIB_FILES tag can be used to specify one or more bib files containing # the reference definitions. This must be a list of .bib files. The .bib @@ -855,16 +823,28 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = @abs_top_srcdir@/src/include \ - @abs_top_srcdir@/src/app \ - @abs_top_srcdir@/src/ble \ - @abs_top_srcdir@/src/inet \ - @abs_top_srcdir@/src/system \ - @abs_top_srcdir@/src/lib/core \ - @abs_top_srcdir@/src/lib/support \ - @abs_top_srcdir@/src/lib/shell \ - @abs_top_srcdir@/src/platform \ - @abs_top_srcdir@/src/transport +INPUT = README.md \ + CONTRIBUTING.md \ + docs/README.md \ + docs/BUILDING.md \ + docs/VSCODE_DEVELOPMENT.md \ + docs/PROJECT_FLOW.md \ + docs/STYLE_GUIDE.md \ + src/app \ + src/ble \ + src/controller \ + src/crypto \ + src/include \ + src/inet \ + src/lib/core \ + src/lib/support \ + src/lib/shell \ + src/platform \ + src/setup_payload \ + src/system \ + src/transport + +USE_MDFILE_AS_MAINPAGE = README.md # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses @@ -886,8 +866,10 @@ INPUT_ENCODING = UTF-8 # If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp, # *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, # *.hh, *.hxx, *.hpp, *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc, -# *.m, *.markdown, *.md, *.mm, *.dox, *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, -# *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf, *.qsf and *.ice. +# *.m, *.markdown, *.md, *.mm, *.dox (to be provided as doxygen C comment), +# *.doc (to be provided as doxygen C comment), *.txt (to be provided as doxygen +# C comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, *.f18, *.f, *.for, *.vhd, +# *.vhdl, *.ucf, *.qsf and *.ice. FILE_PATTERNS = *.c \ *.cc \ @@ -935,7 +917,7 @@ RECURSIVE = YES # Note that relative paths are relative to the directory from which doxygen is # run. -EXCLUDE = +EXCLUDE = # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded @@ -951,7 +933,8 @@ EXCLUDE_SYMLINKS = NO # Note that the wildcards are matched against the file with absolute path, so to # exclude all test directories for example use the pattern */test/* -EXCLUDE_PATTERNS = +EXCLUDE_PATTERNS = */tests/* \ + */dbus/* # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names # (namespaces, classes, functions, etc.) that should be excluded from the @@ -962,7 +945,7 @@ EXCLUDE_PATTERNS = # Note that the wildcards are matched against the file with absolute path, so to # exclude all test directories use the pattern */test/* -EXCLUDE_SYMBOLS = +EXCLUDE_SYMBOLS = */dbus/* # The EXAMPLE_PATH tag can be used to specify one or more files or directories # that contain example code fragments that are included (see the \include @@ -988,7 +971,7 @@ EXAMPLE_RECURSIVE = NO # that contain images that are to be included in the documentation (see the # \image command). -IMAGE_PATH = +IMAGE_PATH = docs/images # The INPUT_FILTER tag can be used to specify a program that doxygen should # invoke to filter for each input file. Doxygen will invoke the filter program @@ -1009,7 +992,7 @@ IMAGE_PATH = # need to set EXTENSION_MAPPING for the extension otherwise the files are not # properly processed by doxygen. -INPUT_FILTER = @abs_top_srcdir@/scripts/helpers/doxygen-format-check.sh +INPUT_FILTER = # The FILTER_PATTERNS tag can be used to specify filters on a per file pattern # basis. Doxygen will compare the file name with each pattern and apply the @@ -1132,35 +1115,6 @@ USE_HTAGS = NO VERBATIM_HEADERS = YES -# If the CLANG_ASSISTED_PARSING tag is set to YES then doxygen will use the -# clang parser (see: http://clang.llvm.org/) for more accurate parsing at the -# cost of reduced performance. This can be particularly helpful with template -# rich C++ code for which doxygen's built-in parser lacks the necessary type -# information. -# Note: The availability of this option depends on whether or not doxygen was -# generated with the -Duse_libclang=ON option for CMake. -# The default value is: NO. - -CLANG_ASSISTED_PARSING = NO - -# If clang assisted parsing is enabled you can provide the compiler with command -# line options that you would normally use when invoking the compiler. Note that -# the include paths will already be set by doxygen for the files and directories -# specified with INPUT and INCLUDE_PATH. -# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES. - -CLANG_OPTIONS = - -# If clang assisted parsing is enabled you can provide the clang parser with the -# path to the compilation database (see: -# http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html) used when the files -# were built. This is equivalent to specifying the "-p" option to a clang tool, -# such as clang-check. These options will then be passed to the parser. -# Note: The availability of this option depends on whether or not doxygen was -# generated with the -Duse_libclang=ON option for CMake. - -CLANG_DATABASE_PATH = - #--------------------------------------------------------------------------- # Configuration options related to the alphabetical class index #--------------------------------------------------------------------------- @@ -1317,9 +1271,9 @@ HTML_TIMESTAMP = YES # If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML # documentation will contain a main index with vertical navigation menus that -# are dynamically created via Javascript. If disabled, the navigation index will +# are dynamically created via JavaScript. If disabled, the navigation index will # consists of multiple levels of tabs that are statically embedded in every HTML -# page. Disable this option to support browsers that do not have Javascript, +# page. Disable this option to support browsers that do not have JavaScript, # like the Qt help browser. # The default value is: YES. # This tag requires that the tag GENERATE_HTML is set to YES. @@ -1587,6 +1541,17 @@ TREEVIEW_WIDTH = 250 EXT_LINKS_IN_WINDOW = NO +# If the HTML_FORMULA_FORMAT option is set to svg, doxygen will use the pdf2svg +# tool (see https://github.com/dawbarton/pdf2svg) or inkscape (see +# https://inkscape.org) to generate formulas as SVG images instead of PNGs for +# the HTML output. These images will generally look nicer at scaled resolutions. +# Possible values are: png The default and svg Looks nicer but requires the +# pdf2svg tool. +# The default value is: png. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_FORMULA_FORMAT = png + # Use this tag to change the font size of LaTeX formulas included as images in # the HTML documentation. When you change the font size after a successful # doxygen run you need to manually remove any form_*.png images from the HTML @@ -1607,8 +1572,14 @@ FORMULA_FONTSIZE = 10 FORMULA_TRANSPARENT = YES +# The FORMULA_MACROFILE can contain LaTeX \newcommand and \renewcommand commands +# to create new LaTeX commands to be used in formulas as building blocks. See +# the section "Including formulas" for details. + +FORMULA_MACROFILE = + # Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see -# https://www.mathjax.org) which uses client side Javascript for the rendering +# https://www.mathjax.org) which uses client side JavaScript for the rendering # instead of using pre-rendered bitmaps. Use this if you do not have LaTeX # installed or if you want to formulas look prettier in the HTML output. When # enabled you may also need to install MathJax separately and configure the path @@ -1636,7 +1607,7 @@ MATHJAX_FORMAT = HTML-CSS # Content Delivery Network so you can quickly see the result without installing # MathJax. However, it is strongly recommended to install a local copy of # MathJax from https://www.mathjax.org before deployment. -# The default value is: https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/. +# The default value is: https://cdn.jsdelivr.net/npm/mathjax@2. # This tag requires that the tag USE_MATHJAX is set to YES. MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest @@ -1678,7 +1649,7 @@ MATHJAX_CODEFILE = SEARCHENGINE = YES # When the SERVER_BASED_SEARCH tag is enabled the search engine will be -# implemented using a web server instead of a web client using Javascript. There +# implemented using a web server instead of a web client using JavaScript. There # are two flavors of web server based searching depending on the EXTERNAL_SEARCH # setting. When disabled, doxygen will generate a PHP script for searching and # an index file used by the script. When EXTERNAL_SEARCH is enabled the indexing @@ -2313,9 +2284,9 @@ HIDE_UNDOC_RELATIONS = YES # http://www.graphviz.org/), a graph visualization toolkit from AT&T and Lucent # Bell Labs. The other options in this section have no effect if this option is # set to NO -# The default value is: YES. +# The default value is: NO. -HAVE_DOT = @DOXYGEN_USE_DOT@ +HAVE_DOT = YES # The DOT_NUM_THREADS specifies the number of dot invocations doxygen is allowed # to run in parallel. When set to 0 doxygen will base this on the number of @@ -2469,9 +2440,7 @@ DIRECTORY_GRAPH = YES # Note: If you choose svg you need to set HTML_FILE_EXTENSION to xhtml in order # to make the SVG files visible in IE 9+ (other browsers do not have this # requirement). -# Possible values are: png, png:cairo, png:cairo:cairo, png:cairo:gd, png:gd, -# png:gd:gd, jpg, jpg:cairo, jpg:cairo:gd, jpg:gd, jpg:gd:gd, gif, gif:cairo, -# gif:cairo:gd, gif:gd, gif:gd:gd, svg, png:gd, png:gd:gd, png:cairo, +# Possible values are: png, jpg, gif, svg, png:gd, png:gd:gd, png:cairo, # png:cairo:gd, png:cairo:cairo, png:cairo:gdiplus, png:gdiplus and # png:gdiplus:gdiplus. # The default value is: png. diff --git a/docs/Makefile.am b/docs/Makefile.am deleted file mode 100644 index 986452be7ac3f3..00000000000000 --- a/docs/Makefile.am +++ /dev/null @@ -1,118 +0,0 @@ -# -# Copyright (c) 2020 Project CHIP Authors -# Copyright (c) 2014-2017 Nest Labs, Inc. -# All rights reserved. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - - -# -# Description: -# This file is the GNU automake template for the CHIP -# API and stack documentation. -# - -include $(abs_top_nlbuild_autotools_dir)/automake/pre.am - -EXTRA_DIST = \ - $(srcdir)/Doxyfile.in \ - $(srcdir)/ChipDoxygenLayout.xml \ - $(top_srcdir)/scripts/helpers/doxygen-format-check.sh \ - $(srcdir)/namespaces.dox \ - $(NULL) - -# -# Override autotool's default notion of the package version variables. -# This ensures that when we create a doc distribution that the -# version is always the current version, not the version when the -# package was bootstrapped. -# -PACKAGE_VERSION = $(shell cat $(top_builddir)/.local-version) -VERSION = $(PACKAGE_VERSION) - -EXTRA_DOCS = \ - $(top_srcdir)/LICENSE \ - $(NULL) - -docdistdir ?= . - -chip_docdist_alias = \ - $(PACKAGE_TARNAME)-docs - -chip_docdist_name = \ - $(chip_docdist_alias)-$(VERSION) - -chip_docdist_archive = \ - $(docdistdir)/$(chip_docdist_name).tar.gz - -CLEANFILES = \ - Doxyfile \ - $(chip_docdist_archive) \ - $(NULL) - -.PHONY: doc docdist - -if CHIP_BUILD_DOCS - -all-local doc: html/index.html - -# -# We choose to manually transform Doxyfile.in into Doxyfile here in -# the makefile rather than in the configure script so that we can take -# advantage of live, at build time (rather than at configure time), -# updating of the package version number. -# - -Doxyfile: $(srcdir)/Doxyfile.in Makefile - $(AM_V_GEN)$(SED) \ - -e "s,\@DOXYGEN_USE_DOT\@,$(DOXYGEN_USE_DOT),g" \ - -e "s,\@PACKAGE_NAME\@,$(PACKAGE_NAME),g" \ - -e "s,\@PACKAGE_VERSION\@,$(PACKAGE_VERSION),g" \ - -e "s,\@PERL\@,$(PERL),g" \ - -e "s,\@abs_builddir\@,$(abs_builddir),g" \ - -e "s,\@abs_srcdir\@,$(abs_srcdir),g" \ - -e "s,\@abs_top_builddir\@,$(abs_top_builddir),g" \ - -e "s,\@abs_top_srcdir\@,$(abs_top_srcdir),g" \ - < "$(srcdir)/Doxyfile.in" > "$(@)" - -html/index.html: Doxyfile - $(AM_V_GEN)$(DOXYGEN) $(<) - -# -# Addition rules and commands to create a documentation-only -# distribution of Chip -# - -$(chip_docdist_name): $(EXTRA_DOCS) html/index.html - $(AM_V_at)rm -f -r $(@) - $(call create-directory) - $(AM_V_at)cp $(EXTRA_DOCS) $(@) - $(AM_V_at)cp -R html $(@) - -$(chip_docdist_archive): $(chip_docdist_name) - $(AM_V_at)echo " TAR $(@)" - $(AM_V_at)tardir="$(<)" && $(am__tar) | GZIP=$(GZIP_ENV) gzip -c > "$(@)" && rm -rf $(<) - -docdist $(chip_docdist_alias): $(chip_docdist_archive) - -clean-local: - $(AM_V_at)rm -f -r html - -else - -doc docdist: - $(error "Documentation support is disabled. Please explicitly enable documentation with `--enable-docs` via `configure` and/or ensure that Doxygen is installed") - -endif # CHIP_BUILD_DOCS - -include $(abs_top_nlbuild_autotools_dir)/automake/post.am diff --git a/scripts/helpers/doxygen-format-check.sh b/scripts/helpers/doxygen-format-check.sh deleted file mode 100755 index b637877ebed506..00000000000000 --- a/scripts/helpers/doxygen-format-check.sh +++ /dev/null @@ -1,35 +0,0 @@ -#!/bin/sh - -# -# Copyright (c) 2020 Project CHIP Authors -# Copyright (c) 2018 Nest Labs, Inc. -# All rights reserved. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -# - -# Managed namespace constructs within CHIP ended up seriously -# confusing Doxygen, and I could not find a nicer way to evaluate -# those macros via Doxygen's PREDEFINED directives. Instead, we -# process the incoming files via this script file. - -FILENAME=${1} -# clang format has difficulty recognizing the -# ChipMakeManagedNamespaceIdentifier() macro as a valid namespace; -# temporarily change the namespace name to something more palatable to -# clang-format - -sed -e 's:^[ ]*namespace[ ]\+ChipMakeManagedNamespaceIdentifier(\([^ ,()]\+\),[ ]*kChipManagedNamespaceDesignation_\([^ ,()]\+\))[ ]*{[ ]*$:namespace \1_\2 {:g' \ - -e 's/NS_ENUM(\([_a-zA-Z0-9][_a-zA-Z0-9]*\)[ ]*,[ ]*\([_a-zA-Z0-9][_a-zA-Z0-9]*\))/ enum \2 : \1 \2; enum \2 : \1/g' \ - -e 's/__attribute__(([^)]*))//g' \ - -e 's/__attribute__([^)]*)//g' "$FILENAME" diff --git a/scripts/helpers/doxygen.sh b/scripts/helpers/doxygen.sh new file mode 100755 index 00000000000000..126b0d60664b5f --- /dev/null +++ b/scripts/helpers/doxygen.sh @@ -0,0 +1,71 @@ +#!/usr/bin/env bash + +# +# Copyright (c) 2020 Project CHIP Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# + +CHIP_ROOT="$(dirname "$0")/../.." +CHIP_NAME="Connected Home over IP" +CHIP_VERSION="$(git rev-parse --short HEAD)" + +die() { + echo " *** ERROR: $*" + exit 1 +} + +install_doxygen() { + if ! doxygen --version >/dev/null 2>&1; then + echo "doxygen not installed. Installing..." + case "$(uname)" in + "Darwin") + brew install doxygen + ;; + "Linux") + apt-get update + apt-get install -y doxygen + ;; + *) + die + ;; + esac + fi +} + +install_graphviz() { + if ! dot -V >/dev/null 2>&1; then + echo "graphviz not installed. Installing..." + case "$(uname)" in + "Darwin") + brew install graphviz + ;; + "Linux") + apt-get update + apt-get install -y graphviz + ;; + *) + die + ;; + esac + fi +} + +install_doxygen +install_graphviz + +cd "$CHIP_ROOT" || exit 1 + +CHIP_NAME=$CHIP_NAME CHIP_VERSION=$CHIP_VERSION doxygen docs/Doxyfile || die "doxygen failed" + +exit 0