Generate index file containing reference information

* README is included so doesn't need to be copied
* Use m2r instead of recommonmark as it provides `mdinclude` directive
* Rename `api-file` role to `source`, make relative to root directory

Sming/Arch/Esp8266/Components/axtls-8266/README.rst

@@ -2,7 +2,3 @@ AXTLS 8266
 ==========
 
 SSL support using the AXTLS library
-
-.. toctree::
-
-   axtls-8266/README

Sming/Arch/Esp8266/Components/custom_heap/README.rst

@@ -5,7 +5,3 @@ Provides an alternative heap memory manager using UMM Malloc.
 
 .. warning::
    Do not enable custom heap allocation and -mforce-l32 compiler flag at the same time.
-
-.. toctree::
-
-   umm_malloc/README

Sming/Arch/Esp8266/Components/esptool/README.rst

@@ -34,10 +34,3 @@ Options
 .. envvar:: COM_SPEED_ESPTOOL
 
    Baud rate to use for flashing device. Default is :envvar:`COM_SPEED`.
-
-Documentation
--------------
-
-.. toctree::
-
-   esptool/README

Sming/Arch/Esp8266/Components/lwip2/README.rst

@@ -2,7 +2,3 @@ Esp8266 LWIP Version 2
 ======================
 
 This Component implements the current Version 2 LWIP stack. Note that at present espconn\_* functions are not supported.
-
-.. toctree::
-
-   lwip2/README

Sming/Arch/Esp8266/Components/pwm_open/README.rst

@@ -2,7 +2,3 @@ Esp8266 Open PWM
 ================
 
 Implements a drop-in replacement for the PWM support provided in the Espressif SDK.
-
-.. toctree::
-
-   new-pwm/README

Sming/Arch/Esp8266/Components/rboot/README.rst

@@ -7,8 +7,3 @@ ease of use.
 This Component also includes esptool2 which rBoot uses to manipulate ROM
 images. Use ``$(ESPTOOL2)`` if you want to use it within your own
 projects.
-
-.. toctree::
-
-   rboot/README
-   esptool2/README

Sming/Arch/Esp8266/README.rst

@@ -11,5 +11,5 @@ Components
    :maxdepth: 1
    :titlesonly:
 
-   Components/sming-arch/README
-   Components/*/README
+   Components/sming-arch/index
+   Components/*/index

Sming/Arch/Host/Components/lwip/README.rst

@@ -13,8 +13,3 @@ Options:
       Standard build
    1
       Enable debugging output
-
-
-.. toctree::
-
-   lwip/README

Sming/Arch/Host/README.rst

@@ -224,8 +224,8 @@ Components
    :maxdepth: 1
    :titlesonly:
 
-   Components/sming-arch/README
-   Components/*/README
+   Components/sming-arch/index
+   Components/*/index
 
 
 todo

Sming/Components/spiffs/README.rst

@@ -2,7 +2,3 @@ SPIFFS for Sming
 ================
 
 This Component provides additional functionality to support SPIFFS running on both Esp8266 and Host architectures.
-
-.. toctree::
-
-   spiffs/README

Sming/Libraries/ArduinoJson5/README.rst

@@ -1,11 +1,4 @@
 ArduinoJson Version 5
 =====================
 
-Provided to support existing applications. New projects should use :library:`ArduinoJson6`
-
-Arduino JSON
-------------
-
-.. toctree::
-
-   ArduinoJson/README
+Provided to support existing applications. New projects should use :library:`ArduinoJson6`.

Sming/README.rst

@@ -93,5 +93,6 @@ Components
 
  .. toctree::
    :glob:
+   :maxdepth: 1
 
-   Components/*/README
+   Components/*/index

docs/Makefile

@@ -103,6 +103,26 @@ 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
+
+# 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 
+ifeq ($(OS),Windows_NT)
+GetIncludePath = GetDocPath
+GetMdIncludePath = GetDocPath
+else
+GetIncludePath = /../../$(patsubst $(abspath $(SMINGDIR))/%,%,$(abspath $1))
+GetMdIncludePath = $(abspath $1)
+endif
+
 include index.mk
 
 # Used to escape generated text so it can be handled as a single line
@@ -139,6 +159,8 @@ CMP_$2_DIRS := \
 CMP_$2_FILES := \
 	$$(call FindSourceFiles,$$(CMP_$2_DIRS)) \
 	$$(wildcard $$(addprefix $$(COMPONENT_PATH)/,$$(COMPONENT_DOCFILES)))
+CMP_$2_README			:= $$(filter $2/README.%,$$(CMP_$2_FILES))
+CMP_$2_FILES			:= $$(filter-out $$(CMP_$2_README),$$(CMP_$2_FILES))
 SOURCE_FILES			+= $$(CMP_$2_FILES)
 
 #
@@ -151,17 +173,17 @@ CMP_$2_DEPENDS := $$(COMPONENT_DEPENDS)
 # If this is an Arch component, then match this Arch only, or **main components** (e.g. Host/heap -> malloc_count)
 #
 ifneq (,$(findstring /Arch/,$2))
-FILTERED_DIRS	:= $$(filter $(dir $2)% $(SMING_HOME)/Components/%,$(COMPONENT_DIRS))
+FILTERED_DIRS := $$(filter $(dir $2)% $(SMING_HOME)/Components/%,$(COMPONENT_DIRS))
 else
-FILTERED_DIRS	:= $(COMPONENT_DIRS)
+FILTERED_DIRS := $(COMPONENT_DIRS)
 endif
 COMPONENT_DEPEND_DIRS := \
 	$(if $(findstring /samples/,$2),/_inc/Sming) \
 	$$(foreach d,$$(patsubst $(SMINGDIR)/%,/_inc/%,$$(foreach c,$$(COMPONENT_DEPENDS),$$(filter %/$$c,$$(FILTERED_DIRS)))),$$d)
 
-CMP_$2_INDEX			:= $$(subst $$(NewLine),\n,$$(call GenIndex,$1,$2,$(patsubst $(SMINGDIR)/%,%,$2)))
+CMP_$2_INDEX := $$(subst $$(NewLine),\n,$$(call GenIndex,$1,$2,$(patsubst $(SMINGDIR)/%,%,$2)))
 
-$$(call GetIncPath,$$(COMPONENT_PATH))/index.rst: $$(call GetIncPath,$$(CMP_$2_FILES))
+$$(call GetIncPath,$$(COMPONENT_PATH))/index.rst: $$(CMP_$2_README) $$(call GetIncPath,$$(CMP_$2_FILES))
 ifeq ($V,1)
 	$$(info Creating $$@...)
 endif
@@ -179,29 +201,35 @@ clean:
 	$(call Sphinx)
 	$(Q) rm -rf $(SOURCE_INCDIR) api
 
-SOURCE_INCDIRS			:= $(call GetIncPath,$(SOURCE_FILE_DIRS))
-SOURCE_INCFILES			:= $(call GetIncPath,$(SOURCE_FILES)) $(addsuffix /index.rst,$(call GetIncPath,$(COMPONENT_DIRS)))
+SOURCE_INCDIRS			:= $(sort $(call GetIncPath,$(COMPONENT_DIRS) $(SOURCE_FILE_DIRS)))
+# Each Sample, Library or Component README.* is included directly rather than added to the toctree
+SOURCE_FILES			:= $(filter-out $(addsuffix /README.%,$(COMPONENT_DIRS)),$(SOURCE_FILES))
+SOURCE_INCFILES			:= $(call GetIncPath,$(SOURCE_FILES))
+COMPONENT_INDEXFILES	:= $(addsuffix /index.rst,$(call GetIncPath,$(COMPONENT_DIRS)))
 
 .PHONY: setup
-setup: checkdirs $(SOURCE_INCFILES)
+setup: checkdirs $(SOURCE_INCFILES) $(COMPONENT_INDEXFILES)
 ifeq ($V,1)
 	$(call PrintVariable,SOURCE_DIRS)
 	$(call PrintVariable,SOURCE_FILES)
+	$(call PrintVariable,COMPONENT_INCFILES)
 endif
 	$(if $(MISSING_README_DIRS),$(call PrintVariable,MISSING_README_DIRS))
 
-# $1 -> document file in Sming code tree
+# Copy source -> dest file
+# $1 -> Source file
+# $2 -> Destination file
 define CopyFileTarget
-$(call GetIncPath,$1): $1
+$1: $2
 	$(Q) cp $$< $$@
 endef
 
-$(foreach f,$(SOURCE_FILES),$(eval $(call CopyFileTarget,$f)))
+$(foreach f,$(SOURCE_FILES),$(eval $(call CopyFileTarget,$(call GetIncPath,$f),$f)))
+
 
 .PHONY: checkdirs
-checkdirs: | $(SOURCE_INCDIRS)
-$(SOURCE_INCDIRS):
-	$(Q) mkdir -p $@
+checkdirs:
+	$(Q) mkdir -p $(SOURCE_INCDIRS)
 
 .PHONY: api
 api: api/xml/index.xml
@@ -216,7 +244,6 @@ endif
 	@echo Generating Doxygen information
 	$(Q) mkdir -p $(@D)
 	$(Q) doxygen 2>$@ 1>$(@D)/doxygen.log
-	$(Q) cp -f $(@D)/html/*.dot $(SOURCE_INCDIR)
 
 api/xml/index.xml: api/error.log
 	@echo "Undocumented:"

docs/index.mk

@@ -0,0 +1,41 @@
+# Generate index.rst file for sample, library or Component
+# This provides a template to automate as much as possible
+# $1 -> name
+# $2 -> Path
+# $3 -> Source path relative to working root directory (SMINGDIR)
+define GenIndex
+$(if $(filter %.rst,$(CMP_$2_README)),
+.. include:: $(call GetIncludePath,$(CMP_$2_README)),
+.. mdinclude:: $(call GetMdIncludePath,$(CMP_$2_README))
+)
+
+References
+------------
+* :source:`Source Code <$3>`
+$(if $(findstring $3=,$(SUBMODULE_URLS)),
+* This is a submodule: `GIT repository <$(call GetSubmoduleURL,$3)>`__.
+)
+$(foreach d,$(sort $(COMPONENT_DEPEND_DIRS)),
+* :doc:`$d/index` Component
+)
+$(foreach l,$(sort $(ARDUINO_LIBRARIES)),
+* :library:`$l` Library
+)
+
+$(if $(COMPONENT_ENVVARS),
+Environment Variables
+---------------------
+$(foreach v,$(COMPONENT_ENVVARS),
+* :envvar:`$v`
+))
+
+$(foreach m,$(COMPONENT_SUBMODULES),
+Submodule: `$m <$(call GetSubmoduleURL,$3/$m)>`__
+-----------------------------------------------------------------------------------------------------
+
+.. toctree::
+
+   $m/README
+
+)
+endef

docs/requirements.txt

@@ -2,6 +2,5 @@
 # list of Python packages used in documentation build
 sphinx==1.8.5
 sphinx-rtd-theme
-recommonmark
-sphinx-markdown-tables
+m2r
 breathe==4.11.1

docs/source/conf.py

@@ -45,8 +45,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'recommonmark',
-    'sphinx_markdown_tables',
+    'm2r',
     'breathe',
     'link-roles',
 ]
@@ -63,7 +62,8 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = []
+exclude_patterns = [
+]
 
 #
 master_doc = 'index'

docs/source/contribute/documentation.rst

@@ -233,11 +233,11 @@ To refer to a sample application README:
 Source code
 ~~~~~~~~~~~
 
-To refer to source code use the full path relative to the `Sming` directory, for example:
+To refer to source code use the path relative to the root working directory, for example:
 
 ::
 
-   See :api-file:`Core/Network/Url.h`
+   See :source:`Sming/Core/Network/Url.h`
 
 If the documentation is built locally, it will use the local file path, otherwise it will create
 a link to the source file on github.

docs/source/features.rst

@@ -12,5 +12,5 @@ The features available are dependent upon the architecture for which Sming is be
    :maxdepth: 1
    :titlesonly:
 
-   /_inc/Sming/README
+   /_inc/Sming/index
    /_inc/Sming/Arch/*/README

docs/source/libraries/index.rst

@@ -12,5 +12,5 @@ These are all the libraries included with Sming:
    :maxdepth: 1
    :titlesonly:
 
-   /_inc/Sming/Libraries/*/README
+   /_inc/Sming/Libraries/*/index
 

docs/source/link-roles.py

@@ -37,15 +37,15 @@ def setup(app):
     else:
         basepath = baseurl + '/blob/' + get_github_rev()
 
-    app.add_role('api-file', autolink(basepath + '/Sming/{}'))
+    app.add_role('source', autolink(basepath + '/{}'))
     app.add_role('issue', autolink('Issue #{0} <' + baseurl + '/issue/{0}>'))
     app.add_role('pull-request', autolink('Pull Request #{0} <' + baseurl + '/pull/{0}>'))
 
-    app.add_role('sample', doclink('/_inc/samples/{}/README'))
-    app.add_role('component', doclink('/_inc/Sming/Components/{}/README'))
-    app.add_role('component-esp8266', doclink('/_inc/Sming/Arch/Esp8266/Components/{}/README'))
-    app.add_role('component-host', doclink('/_inc/Sming/Arch/Host/Components/{}/README'))
-    app.add_role('library', doclink('/_inc/Sming/Libraries/{}/README'))
+    app.add_role('sample', doclink('/_inc/samples/{}/index'))
+    app.add_role('component', doclink('/_inc/Sming/Components/{}/index'))
+    app.add_role('component-esp8266', doclink('/_inc/Sming/Arch/Esp8266/Components/{}/index'))
+    app.add_role('component-host', doclink('/_inc/Sming/Arch/Host/Components/{}/index'))
+    app.add_role('library', doclink('/_inc/Sming/Libraries/{}/index'))
 
 # Insert a link to a file or issue in the repo
 # Both pattern and user text may use optional format, e.g. `title <link {}>`

docs/source/samples/index.rst

@@ -13,4 +13,4 @@ List of sample projects
    :maxdepth: 1
    :titlesonly:
 
-   /_inc/samples/*/README
+   /_inc/samples/*/index