From a06d6ec211cbae8e09a0e9562d4e50942a94c84d Mon Sep 17 00:00:00 2001 From: mikee47 Date: Sun, 21 Jul 2019 16:58:50 +0100 Subject: [PATCH] Replace `api` section with generated doxygen HTML, including graphs --- .travis.yml | 1 + docs/Doxyfile | 20 +++++++++++++++----- docs/Makefile | 23 +++++++---------------- docs/README.md | 17 ++++++++++++----- docs/source/api/index.rst | 14 -------------- docs/source/api/network/index.rst | 5 ----- docs/source/api/platform/index.rst | 5 ----- docs/source/api/start.rst | 7 +++++++ docs/source/api/storage/index.rst | 12 ------------ docs/source/api/streams.rst | 10 ---------- docs/source/api/system.rst | 5 ----- docs/source/api/wiring.rst | 11 ----------- docs/source/conf.py | 4 ++++ docs/source/index.rst | 2 +- 14 files changed, 47 insertions(+), 89 deletions(-) delete mode 100644 docs/source/api/index.rst delete mode 100644 docs/source/api/network/index.rst delete mode 100644 docs/source/api/platform/index.rst create mode 100644 docs/source/api/start.rst delete mode 100644 docs/source/api/storage/index.rst delete mode 100644 docs/source/api/streams.rst delete mode 100644 docs/source/api/system.rst delete mode 100644 docs/source/api/wiring.rst diff --git a/.travis.yml b/.travis.yml index bf22bed09e..adb68c3365 100644 --- 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 index b4521dc297..aa8b2abfb0 100644 --- 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 index 38394b6b3f..dfb4a1a7be 100644 --- 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 index 40b21775fb..d0564f9f54 100644 --- 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 deleted file mode 100644 index 859eb813f1..0000000000 --- a/docs/source/api/index.rst +++ /dev/null @@ -1,14 +0,0 @@ -***************** -API Documentation -***************** - -Overview of API, relationship to Arduino, etc. - -.. toctree:: - :glob: - :maxdepth: 2 - - network/index - platform/index - storage/index - * diff --git a/docs/source/api/network/index.rst b/docs/source/api/network/index.rst deleted file mode 100644 index 467cb2187f..0000000000 --- a/docs/source/api/network/index.rst +++ /dev/null @@ -1,5 +0,0 @@ -********** -Networking -********** - -To be completed. diff --git a/docs/source/api/platform/index.rst b/docs/source/api/platform/index.rst deleted file mode 100644 index a0b623ca3b..0000000000 --- a/docs/source/api/platform/index.rst +++ /dev/null @@ -1,5 +0,0 @@ -************ -Platform API -************ - -To be completed. diff --git a/docs/source/api/start.rst b/docs/source/api/start.rst new file mode 100644 index 0000000000..a038cd5bf3 --- /dev/null +++ b/docs/source/api/start.rst @@ -0,0 +1,7 @@ +***************** +API Documentation +***************** + +This is a separate section built using DOXYGEN. + +`Doxygen API `_ diff --git a/docs/source/api/storage/index.rst b/docs/source/api/storage/index.rst deleted file mode 100644 index 775dde8c69..0000000000 --- a/docs/source/api/storage/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -*********** -Storage API -*********** - -To be completed. - -To cover: - -* SPIFFS -* FlashString -* Flash memory macros, etc. - diff --git a/docs/source/api/streams.rst b/docs/source/api/streams.rst deleted file mode 100644 index 9bf23ca08b..0000000000 --- a/docs/source/api/streams.rst +++ /dev/null @@ -1,10 +0,0 @@ -******* -Streams -******* - -IDataSourceStream, etc. - -.. doxygenclass:: Print - -.. doxygengroup:: stream - :members: diff --git a/docs/source/api/system.rst b/docs/source/api/system.rst deleted file mode 100644 index b715050d84..0000000000 --- a/docs/source/api/system.rst +++ /dev/null @@ -1,5 +0,0 @@ -********** -System API -********** - -To be completed. diff --git a/docs/source/api/wiring.rst b/docs/source/api/wiring.rst deleted file mode 100644 index d888bd5ab9..0000000000 --- a/docs/source/api/wiring.rst +++ /dev/null @@ -1,11 +0,0 @@ -********** -Wiring API -********** - - -To be completed. - -Include details of customisations, e.g. addition of FlashString, modifications to String, etc. - - -.. doxygenclass:: String diff --git a/docs/source/conf.py b/docs/source/conf.py index 9288262e2d..442917cb39 100644 --- 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 index 49f1798398..19b12304bb 100644 --- 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