Add support for documentation on readthedocs.io
This commit is contained in:
George Oikonomou
parent
0cee22fd71
commit
57692d21f9
|
|
@ -16,6 +16,7 @@ obj_*
|
|||
Makefile.target
|
||||
Makefile.*.defines
|
||||
tools/doxygen/html
|
||||
tools/readthedocs/_build
|
||||
patches-*
|
||||
tools/serial-io/tunslip6
|
||||
tools/serial-io/serialdump
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
@ -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__,))
|
||||
|
|
@ -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'
|
||||
|
|
@ -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
|
||||
|
|
@ -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('▼');
|
||||
$(this).show();
|
||||
} else if (l==level+1) {
|
||||
i.removeClass('iconfclosed iconfopen').addClass('iconfclosed');
|
||||
a.html('▶');
|
||||
$(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('▶');
|
||||
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('▼');
|
||||
// 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('▶');
|
||||
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 });
|
||||
});
|
||||
});
|
||||
Loading…
Reference in New Issue