diff --git a/.gitignore b/.gitignore index 31afb98b3..91721ed08 100644 --- a/.gitignore +++ b/.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 diff --git a/tools/readthedocs/Makefile b/tools/readthedocs/Makefile new file mode 100644 index 000000000..ecf5b58d4 --- /dev/null +++ b/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) diff --git a/tools/readthedocs/api-doc.py b/tools/readthedocs/api-doc.py new file mode 100644 index 000000000..c59b0864e --- /dev/null +++ b/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__,)) diff --git a/tools/readthedocs/conf.py b/tools/readthedocs/conf.py new file mode 100644 index 000000000..50e43737e --- /dev/null +++ b/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' diff --git a/tools/readthedocs/index.rst b/tools/readthedocs/index.rst new file mode 100644 index 000000000..794c0866b --- /dev/null +++ b/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 diff --git a/tools/readthedocs/js/dynsections.js b/tools/readthedocs/js/dynsections.js new file mode 100644 index 000000000..537e3e498 --- /dev/null +++ b/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