Replace api section with generated doxygen HTML, including graphs

SmingHub · Jul 22, 2019 · a06d6ec · a06d6ec
1 parent db311d6
commit a06d6ec
Show file tree

Hide file tree

Showing 14 changed files with 47 additions and 89 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -18,6 +18,7 @@ jobs:
         - python3-sphinx
         - python3-pip
         - python3-setuptools
+        - graphviz-dev
     env: SMING_ARCH=Host
 
   - stage: build

diff --git a/docs/Doxyfile b/docs/Doxyfile
@@ -5,7 +5,7 @@
 
 PROJECT_NAME           = "Sming Framework API"
 PROJECT_BRIEF          = "Sming - Open Source framework for high efficiency WiFi SoC ESP8266 native development with C++ language."
-OUTPUT_DIRECTORY       = api
+OUTPUT_DIRECTORY       =
 
 # If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then
 # doxygen will generate a detailed section even if there is only a brief
@@ -94,7 +94,7 @@ WARN_LOGFILE           = api/error.log
 
 STRIP_FROM_PATH        = $(SMING_HOME)
 
-INPUT = \
+INPUT = api.dox sdk.dox \
 	../Sming/Core \
 	../Sming/Platform \
 	../Sming/Services \
@@ -311,16 +311,26 @@ COLS_IN_ALPHA_INDEX    = 5
 IGNORE_PREFIX          =
 
 ##
-GENERATE_HTML          = NO
+GENERATE_HTML          = YES
+HTML_OUTPUT            = api/html/api
+
 GENERATE_LATEX         = NO
 GENERATE_MAN           = NO
 GENERATE_RTF           = NO
-HAVE_DOT               = NO
+
+# Graph creation
+HAVE_DOT               = YES
+DOT_MULTI_TARGETS      = YES
+DOT_IMAGE_FORMAT       = svg
+INTERACTIVE_SVG        = NO
+DOT_CLEANUP            = YES
+GENERATE_TREEVIEW      = YES
 
 WARN_IF_UNDOCUMENTED   = NO
 
+#
 GENERATE_XML           = YES
-XML_OUTPUT             = xml
+XML_OUTPUT             = api/xml
 
 # If the XML_PROGRAMLISTING tag is set to YES, doxygen will dump the program
 # listings (including syntax highlighting and cross-referencing information) to

diff --git a/docs/Makefile b/docs/Makefile
@@ -103,24 +103,15 @@ define GetSubmoduleURL
 $(subst $1=,,$(filter $1=%,$(SUBMODULE_URLS)))
 endef
 
-# Get a path string acceptable to sphinx
-# $1 -> Path to file
-ifeq ($(OS),Windows_NT)
-DRIVE		:= $(firstword $(subst /, ,$(CURDIR)))
-GetDocPath	= $(DRIVE):/$(subst /$(DRIVE)/,,$(abspath $1))
-else
-GetDocPath	= $(abspath $1)
-endif
+# If a Sphinx 'include' directive starts with '/' that's the source directory, so we need a path relative to that
+GetIncludePath = /../$(SMINGDIR)/$(patsubst $(abspath $(SMINGDIR))/%,%,$(abspath $1))
 
-# This is used with 'include' directives
-# For Windows, sphinx has a problem with the /c/ style drives and wants c:/ instead
-# For linux, 'include' requires a relative path. If it starts with '/' that's taken as the source directory 
+# For Windows, Sphinx has a problem with the /c/ style drives and wants c:/ instead
 ifeq ($(OS),Windows_NT)
-GetIncludePath = GetDocPath
-GetMdIncludePath = GetDocPath
+DRIVE				:= $(firstword $(subst /, ,$(CURDIR)))
+GetMdIncludePath	= $(DRIVE):/$(subst /$(DRIVE)/,,$(abspath $1))
 else
-GetIncludePath = /../../$(patsubst $(abspath $(SMINGDIR))/%,%,$(abspath $1))
-GetMdIncludePath = $(abspath $1)
+GetMdIncludePath	= $(abspath $1)
 endif
 
 include index.mk
@@ -242,7 +233,7 @@ ifndef DOXYGEN
 	$(error doxygen not found - not building API docs)
 endif
 	@echo Generating Doxygen information
-	$(Q) mkdir -p $(@D)
+	$(Q) mkdir -p api api/html
 	$(Q) doxygen 2>$@ 1>$(@D)/doxygen.log
 
 api/xml/index.xml: api/error.log

diff --git a/docs/README.md b/docs/README.md
@@ -12,17 +12,24 @@ information is obtained from the various README files associated with the source
 
 Should already be available as part of Sming build system
 
-### doxygen
-
-See [http://www.doxygen.nl/](http://www.doxygen.nl/)
+### doxygen & graphviz
 
 For Linux:
 
-	sudo apt install doxygen
+	sudo apt install doxygen graphviz-dev
+
+For Windows, see:
+
+* *Doxygen* [www.doxygen.nl](http://www.doxygen.nl/)
+* *Graphviz* [graphviz.org](https://graphviz.org/)
+
+GraphViz is used by Doxygen (and Sphinx) to render graphs from .dot files.
 
 ### Python 3 + Sphinx
 
-For Linux, run `sudo apt install python3-sphinx python3-pip python3-setuptools`.
+For Linux:
+
+	sudo apt install python3-sphinx python3-pip python3-setuptools
 
 For Windows, see [Sphinx Installation Guide](https://www.sphinx-doc.org/en/master/usage/installation.html).
 

diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst
diff --git a/docs/source/api/network/index.rst b/docs/source/api/network/index.rst
diff --git a/docs/source/api/platform/index.rst b/docs/source/api/platform/index.rst
diff --git a/docs/source/api/start.rst b/docs/source/api/start.rst
@@ -0,0 +1,7 @@
+*****************
+API Documentation
+*****************
+
+This is a separate section built using DOXYGEN.
+
+`Doxygen API <index.html>`_
diff --git a/docs/source/api/storage/index.rst b/docs/source/api/storage/index.rst
diff --git a/docs/source/api/streams.rst b/docs/source/api/streams.rst
diff --git a/docs/source/api/system.rst b/docs/source/api/system.rst
diff --git a/docs/source/api/wiring.rst b/docs/source/api/wiring.rst
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -92,6 +92,10 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+html_extra_path = [
+    '../api/html'
+]
+
 
 ##
 subprocess.call(["make", "-C", "../../Sming", "submodules", "SMING_ARCH=Host"])

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -52,7 +52,7 @@ Summary
    features
    samples
    libraries
-   api/index
+   api/start
    information/index
    experimental/index
    contribute/index