Get Doxygen documentation to be independent of the build system (proj…

…ect-chip#2703)
mspang · Sep 18, 2020 · 9754e3d · 9754e3d
1 parent daefdc4
commit 9754e3d
Show file tree

Hide file tree

Showing 9 changed files with 222 additions and 343 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -1,39 +1,40 @@
 <doxygenlayout version="1.0">
-  <!-- Generated by doxygen 1.8.6 -->
+  <!-- Generated by doxygen 1.8.18 -->
   <!-- Navigation index tabs for HTML output -->
   <navindex>
-    <tab type="mainpage" visible="yes" title="">
-    <tab type="usergroup" title="Architectural">
-      <tab type="pages" visible="yes" title="" intro=""/>
-      <tab type="usergroup" visible="yes" title="Pairing" intro="">
-        <tab type="user" url="@ref PassiveRendezvous" title="PassiveRendezvous" intro=""/>
-        <tab type="user" url="@ref RemotePassiveRendezvous" title="RemotePassiveRendezvous" intro=""/>
-        <tab type="usergroup" url="@ref NetworkProvisioning" title="NetworkProvisioning" intro="">
-          <tab type="user" url="@ref DeviceControl" title="DeviceControl" intro=""/>
-          <tab type="user" url="@ref TokenPairing" title="TokenPairing" intro=""/>
-        </tab>
-        <tab type="user" url="@ref FabricProvisioning" title="FabricProvisioning" intro=""/>
-        <tab type="user" url="@ref ServiceProvisioning" title="ServiceProvisioning" intro=""/>
-      </tab>
-      <tab type="namespaces" visible="yes" title="">
-        <tab type="namespacelist" visible="yes" title="" intro=""/>
-        <tab type="namespacemembers" visible="yes" title="" intro=""/>
-      </tab>
+    <tab type="mainpage" visible="yes" title=""/>
+    <tab type="pages" visible="yes" title="" intro=""/>
+    <tab type="namespaces" visible="yes" title="">
+      <tab type="namespacelist" visible="yes" title="" intro=""/>
+      <tab type="namespacemembers" visible="yes" title="" intro=""/>
+    </tab>
+    <tab type="interfaces" visible="yes" title="">
+      <tab type="interfacelist" visible="yes" title="" intro=""/>
+      <tab type="interfaceindex" visible="$ALPHABETICAL_INDEX" title=""/> 
+      <tab type="interfacehierarchy" visible="yes" title="" intro=""/>
     </tab>
     <tab type="classes" visible="yes" title="">
       <tab type="classlist" visible="yes" title="" intro=""/>
-      <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
+      <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/> 
       <tab type="hierarchy" visible="yes" title="" intro=""/>
       <tab type="classmembers" visible="yes" title="" intro=""/>
     </tab>
+    <tab type="structs" visible="yes" title="">
+      <tab type="structlist" visible="yes" title="" intro=""/>
+      <tab type="structindex" visible="$ALPHABETICAL_INDEX" title=""/> 
+    </tab>
+    <tab type="exceptions" visible="yes" title="">
+      <tab type="exceptionlist" visible="yes" title="" intro=""/>
+      <tab type="exceptionindex" visible="$ALPHABETICAL_INDEX" title=""/> 
+      <tab type="exceptionhierarchy" visible="yes" title="" intro=""/>
+    </tab>
     <tab type="files" visible="yes" title="">
       <tab type="filelist" visible="yes" title="" intro=""/>
       <tab type="globals" visible="yes" title="" intro=""/>
     </tab>
-    <tab type="examples" visible="yes" title="" intro=""/>
+    <tab type="examples" visible="yes" title="" intro=""/>  
   </navindex>
 
-
   <!-- Layout definition for a class page -->
   <class>
     <briefdescription visible="yes"/>
@@ -99,8 +100,13 @@
     <memberdecl>
       <nestednamespaces visible="yes" title=""/>
       <constantgroups visible="yes" title=""/>
+      <interfaces visible="yes" title=""/>
       <classes visible="yes" title=""/>
+      <structs visible="yes" title=""/>
+      <exceptions visible="yes" title=""/>
       <typedefs title=""/>
+      <sequences title=""/>
+      <dictionaries title=""/>
       <enums title=""/>
       <functions title=""/>
       <variables title=""/>
@@ -110,6 +116,8 @@
     <memberdef>
       <inlineclasses title=""/>
       <typedefs title=""/>
+      <sequences title=""/>
+      <dictionaries title=""/>
       <enums title=""/>
       <functions title=""/>
       <variables title=""/>
@@ -125,11 +133,16 @@
     <includedbygraph visible="$INCLUDED_BY_GRAPH"/>
     <sourcelink visible="yes"/>
     <memberdecl>
+      <interfaces visible="yes" title=""/>
       <classes visible="yes" title=""/>
+      <structs visible="yes" title=""/>
+      <exceptions visible="yes" title=""/>
       <namespaces visible="yes" title=""/>
       <constantgroups visible="yes" title=""/>
       <defines title=""/>
       <typedefs title=""/>
+      <sequences title=""/>
+      <dictionaries title=""/>
       <enums title=""/>
       <functions title=""/>
       <variables title=""/>
@@ -140,6 +153,8 @@
       <inlineclasses title=""/>
       <defines title=""/>
       <typedefs title=""/>
+      <sequences title=""/>
+      <dictionaries title=""/>
       <enums title=""/>
       <functions title=""/>
       <variables title=""/>
@@ -159,6 +174,8 @@
       <classes visible="yes" title=""/>
       <defines title=""/>
       <typedefs title=""/>
+      <sequences title=""/>
+      <dictionaries title=""/>
       <enums title=""/>
       <enumvalues title=""/>
       <functions title=""/>
@@ -178,6 +195,8 @@
       <inlineclasses title=""/>
       <defines title=""/>
       <typedefs title=""/>
+      <sequences title=""/>
+      <dictionaries title=""/>
       <enums title=""/>
       <enumvalues title=""/>
       <functions title=""/>