Merge pull request #547 from g-oikonomou/contrib/readthedocs

Add support for documentation on readthedocs.io

.gitignore

@@ -16,6 +16,7 @@ obj_*
 Makefile.target
 Makefile.*.defines
 tools/doxygen/html
+tools/readthedocs/_build
 patches-*
 tools/serial-io/tunslip6
 tools/serial-io/serialdump

.travis.yml

@@ -62,7 +62,7 @@ env:
     - TEST_NAME='simulation-base'
     - TEST_NAME='ieee802154'
     - TEST_NAME='compile-nxp-ports'
-    - TEST_NAME='doxygen'
+    - TEST_NAME='documentation'
     - TEST_NAME='compile-tools'
     - TEST_NAME='native-runs'
     - TEST_NAME='ipv6'

tests/00-documentation/Makefile

@@ -24,35 +24,56 @@
 # LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 # OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 # SUCH DAMAGE.
+TOOLS_DIR = ../../tools
 
-DOCDIR=../../tools/doxygen
+DOXYGEN = doxygen
+DOXYGEN_DIR = $(TOOLS_DIR)/doxygen
+DOXYGEN_LOG = $(DOXYGEN).log
+DOXYGEN_ERR = $(DOXYGEN).err
+
+RAEDTHEDOCS = readthedocs
+READTHEDOCS_DIR = $(TOOLS_DIR)/readthedocs
+READTHEDOCS_LOG = $(RAEDTHEDOCS).log
+READTHEDOCS_ERR = $(RAEDTHEDOCS).err
+
+CLEAN_TARGETS += $(DOXYGEN_LOG) $(DOXYGEN_ERR)
+CLEAN_TARGETS += $(READTHEDOCS_LOG) $(READTHEDOCS_ERR)
 
 all: clean summary
 
 doxygen:
-	-@$(MAKE) -C $(DOCDIR) 2> doxygen.err > /dev/null
+	-@$(MAKE) -C $(DOXYGEN_DIR) 2> $(DOXYGEN_ERR) > /dev/null
 
-summary: doxygen
+readthedocs:
+	-@$(MAKE) -C $(READTHEDOCS_DIR) 2> $(READTHEDOCS_ERR) > /dev/null
+
+summary: doxygen readthedocs
 	@( \
 		1> summary; \
-		if [ -s doxygen.err ] ; then \
+		if [ -s $(DOXYGEN_ERR) ] ; then \
-			echo "Doxygen: TEST FAIL" | tee summary; \
+			echo "Doxygen: TEST FAIL" | tee -a summary; \
 			echo "Errors:"; \
-			cat doxygen.err; \
+			cat $(DOXYGEN_ERR); \
 		fi ; \
-		if [ -s $(DOCDIR)/doxygen.log ] ; then \
+		if [ -s $(DOXYGEN_DIR)/doxygen.log ] ; then \
-			echo "Doxygen: TEST FAIL" | tee summary; \
+			echo "Doxygen: TEST FAIL" | tee -a summary; \
 			echo "Warnings:"; \
-			cat $(DOCDIR)/doxygen.log; \
+			cat $(DOXYGEN_DIR)/doxygen.log; \
+		fi ; \
+		if [ -s $(READTHEDOCS_ERR) ] ; then \
+			echo "Readthedocs: TEST FAIL" | tee -a summary; \
+			echo "Errors:"; \
+			cat $(READTHEDOCS_ERR); \
 		fi ; \
 		if [ ! -s summary ] ; then \
-			echo "Doxygen: TEST OK (no warning nor error)" | tee summary; \
+			echo "Documentation: TEST OK (no warning nor error)" | tee summary; \
 		fi ; \
 	)
-	@rm doxygen.err
+	@rm -f $(CLEAN_TARGETS)
 	@echo "========== Summary =========="
 	@cat summary
 
 clean:
-	@rm -f summary doxygen.err
+	@rm -f summary $(CLEAN_TARGETS)
-	@$(MAKE) -C $(DOCDIR) clean
+	@$(MAKE) -C $(DOXYGEN_DIR) clean
+	@$(MAKE) -C $(READTHEDOCS_DIR) clean

tools/docker/Dockerfile

@@ -3,7 +3,7 @@ FROM 32bit/ubuntu:16.04
 # Tools
 RUN apt-get update && \
   apt-get install -y --no-install-recommends \
-  build-essential doxygen git wget unzip python-serial \
+  build-essential doxygen git wget unzip python-serial python-pip \
   default-jdk ant srecord iputils-tracepath rlwrap \
   mosquitto mosquitto-clients \
   && apt-get clean
@@ -42,6 +42,12 @@ RUN wget https://developer.nordicsemi.com/nRF5_IoT_SDK/nRF5_IoT_SDK_v0.9.x/nrf5_
 
 ENV NRF52_SDK_ROOT /usr/nrf52-sdk
 
+# Install sphinx and sphinx_rtd_theme, required for building and testing the
+# readthedocs API documentation
+RUN pip install --upgrade pip
+RUN pip install setuptools
+RUN pip install sphinx_rtd_theme sphinx
+
 # Create user, enable X forwarding, add to group dialout
 # -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix
 RUN export uid=1000 gid=1000 && \

tools/readthedocs/Makefile

@@ -0,0 +1,19 @@
+# Makefile used to generate documentation with sphinx, which is used on
+# readthedocs. Use this Makefile to test readthedocs generation locally on
+# your computer.
+#
+# For this to work, you will need to install sphinx and sphinx_rtd_theme. They
+# can be installed through pip
+.PHONY = clean all readthedocs
+
+SPHINX = sphinx-build
+SPHINX_CONF_DIR = .
+SPHINX_OUT_DIR = _build
+
+all: readthedocs
+
+clean:
+	rm -rf $(SPHINX_OUT_DIR)
+
+readthedocs:
+	$(SPHINX) -b html $(SPHINX_CONF_DIR) $(SPHINX_OUT_DIR)

tools/readthedocs/api-doc.py

@@ -0,0 +1,65 @@
+# Sphinx extension that builds Contiki-NG documentation and copies it over to
+# the sphinx build dir
+import subprocess
+from sphinx.util import logging
+logger = logging.getLogger(__name__)
+
+
+api_doc_defaults = {
+    'doxygen_src_dir': '../doxygen',
+    'doxygen_out_dir': 'html',
+    'doxygen_suppress_out': True,
+    'doxygen_build': True,
+}
+
+
+def api_doc_build(app, exception):
+    if exception is not None:
+        logger.warning('%s exiting without building' % (__name__,))
+        return
+
+    if app.config.api_doc_doxygen_build:
+        make_invocation_suffix = ('> /dev/null'
+                                  if app.config.api_doc_doxygen_suppress_out
+                                  else '')
+        make_invocation = ' '.join(('make -C',
+                                    app.config.api_doc_doxygen_src_dir,
+                                    make_invocation_suffix))
+
+        logger.info('%s building API docs from "%s"'
+                     % (__name__, app.config.api_doc_doxygen_src_dir))
+        logger.info('%s executing "%s"'
+                     % (__name__, make_invocation))
+
+        subprocess.call(make_invocation, shell=True)
+
+        api_doc_build_dir = "/".join((app.config.api_doc_doxygen_src_dir,
+                                      app.config.api_doc_doxygen_out_dir))
+        api_doc_static_api_dir = "/".join((app.outdir, '_api'))
+
+        logger.info('%s moving "%s" to "%s"'
+                     % (__name__, api_doc_build_dir, api_doc_static_api_dir))
+        subprocess.call(' '.join(('mv', api_doc_build_dir,
+                                  api_doc_static_api_dir)),
+                        shell=True)
+
+        # Fundamentally a workaround: Readthedocs doxygen build plain refulses
+        # to build the same html/*.js files as local builds do. So we ship them
+        # and we copy them over to the output dir by force, till readthedocs
+        # starts behaving, hopefully in the near future
+        subprocess.call(' '.join(('cp js/dynsections.js',
+                                  api_doc_static_api_dir)),
+                        shell=True)
+
+
+def setup(app):
+    for k, v in api_doc_defaults.items():
+        config_val = 'api_doc_' + k
+        logger.debug('Add config value %s: %s' %(config_val, v))
+        app.add_config_value(config_val, v, '')
+
+    # We will build and copy the docs after the end of the sphinx build, and.
+    # only if it has been successful. Regsiter for the build-finished event.
+    app.connect('build-finished', api_doc_build)
+
+    logger.info('%s initialised' % (__name__,))

tools/readthedocs/conf.py

@@ -0,0 +1,112 @@
+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = u'Contiki-NG'
+copyright = u'2018, Contiki-NG maintainers and contributors'
+author = u'Contiki-NG maintainers and contributors'
+
+# The short X.Y version
+version = u''
+# The full version, including alpha/beta/rc tags
+release = u''
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'api-doc'
+]
+
+# api-doc configuration
+api_doc_doxygen_src_dir = '../doxygen'
+api_doc_doxygen_out_dir = 'html'
+api_doc_doxygen_suppress_out = True
+api_doc_doxygen_build = True
+
+# Add any paths that contain templates here, relative to this directory.
+#templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# 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 = [u'_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+#html_static_path = ['_static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'Contiki-NGdoc'

tools/readthedocs/index.rst

@@ -0,0 +1,23 @@
+Contiki-NG API documentation!
+=============================
+
+These pages host Contiki-NG's API documentation.
+
+The primary target audience
+consists developers who want to develop an application with Contiki-NG or who
+want to modify Contiki-NG itself.
+
+For guides and tutorials, visit the `Contiki-NG wiki`_.
+
+Index
+=====
+* `API Home`_
+* `List of Modules`_
+* `Data Structure Index`_
+* `Index of Files`_
+
+.. _Contiki-NG wiki: https://github.com/contiki-ng/contiki-ng/wiki
+.. _API Home: _api/index.html
+.. _List of Modules: _api/modules.html
+.. _Data Structure Index: _api/annotated.html
+.. _Index of Files: _api/files.html

tools/readthedocs/js/dynsections.js

@@ -0,0 +1,127 @@
+/*
+ @licstart  The following is the entire license notice for the
+ JavaScript code in this file.
+
+ Copyright (C) 1997-2017 by Dimitri van Heesch
+
+ This program is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation; either version 2 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License along
+ with this program; if not, write to the Free Software Foundation, Inc.,
+ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+ @licend  The above is the entire license notice
+ for the JavaScript code in this file
+ */
+function toggleVisibility(linkObj)
+{
+ var base = $(linkObj).attr('id');
+ var summary = $('#'+base+'-summary');
+ var content = $('#'+base+'-content');
+ var trigger = $('#'+base+'-trigger');
+ var src=$(trigger).attr('src');
+ if (content.is(':visible')===true) {
+   content.hide();
+   summary.show();
+   $(linkObj).addClass('closed').removeClass('opened');
+   $(trigger).attr('src',src.substring(0,src.length-8)+'closed.png');
+ } else {
+   content.show();
+   summary.hide();
+   $(linkObj).removeClass('closed').addClass('opened');
+   $(trigger).attr('src',src.substring(0,src.length-10)+'open.png');
+ }
+ return false;
+}
+
+function updateStripes()
+{
+  $('table.directory tr').
+       removeClass('even').filter(':visible:even').addClass('even');
+}
+
+function toggleLevel(level)
+{
+  $('table.directory tr').each(function() {
+    var l = this.id.split('_').length-1;
+    var i = $('#img'+this.id.substring(3));
+    var a = $('#arr'+this.id.substring(3));
+    if (l<level+1) {
+      i.removeClass('iconfopen iconfclosed').addClass('iconfopen');
+      a.html('&#9660;');
+      $(this).show();
+    } else if (l==level+1) {
+      i.removeClass('iconfclosed iconfopen').addClass('iconfclosed');
+      a.html('&#9654;');
+      $(this).show();
+    } else {
+      $(this).hide();
+    }
+  });
+  updateStripes();
+}
+
+function toggleFolder(id)
+{
+  // the clicked row
+  var currentRow = $('#row_'+id);
+
+  // all rows after the clicked row
+  var rows = currentRow.nextAll("tr");
+
+  var re = new RegExp('^row_'+id+'\\d+_$', "i"); //only one sub
+
+  // only match elements AFTER this one (can't hide elements before)
+  var childRows = rows.filter(function() { return this.id.match(re); });
+
+  // first row is visible we are HIDING
+  if (childRows.filter(':first').is(':visible')===true) {
+    // replace down arrow by right arrow for current row
+    var currentRowSpans = currentRow.find("span");
+    currentRowSpans.filter(".iconfopen").removeClass("iconfopen").addClass("iconfclosed");
+    currentRowSpans.filter(".arrow").html('&#9654;');
+    rows.filter("[id^=row_"+id+"]").hide(); // hide all children
+  } else { // we are SHOWING
+    // replace right arrow by down arrow for current row
+    var currentRowSpans = currentRow.find("span");
+    currentRowSpans.filter(".iconfclosed").removeClass("iconfclosed").addClass("iconfopen");
+    currentRowSpans.filter(".arrow").html('&#9660;');
+    // replace down arrows by right arrows for child rows
+    var childRowsSpans = childRows.find("span");
+    childRowsSpans.filter(".iconfopen").removeClass("iconfopen").addClass("iconfclosed");
+    childRowsSpans.filter(".arrow").html('&#9654;');
+    childRows.show(); //show all children
+  }
+  updateStripes();
+}
+
+
+function toggleInherit(id)
+{
+  var rows = $('tr.inherit.'+id);
+  var img = $('tr.inherit_header.'+id+' img');
+  var src = $(img).attr('src');
+  if (rows.filter(':first').is(':visible')===true) {
+    rows.css('display','none');
+    $(img).attr('src',src.substring(0,src.length-8)+'closed.png');
+  } else {
+    rows.css('display','table-row'); // using show() causes jump in firefox
+    $(img).attr('src',src.substring(0,src.length-10)+'open.png');
+  }
+}
+/* @license-end */
+
+$(document).ready(function() {
+  $('.code,.codeRef').each(function() {
+    $(this).data('powertip',$('#'+$(this).attr('href').replace(/.*\//,'').replace(/[^a-z_A-Z0-9]/g,'_')).html());
+    $(this).powerTip({ placement: 's', smartPlacement: true, mouseOnToPopup: true });
+  });
+});