From: Marek VavruĊĦa Date: Wed, 18 Mar 2015 14:48:25 +0000 (+0100) Subject: doc: started doxygen/sphinx documentation with breathe for apiref X-Git-Tag: v1.0.0-beta1~295^2~2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=8ce0280f05b806f476ed51625bedefe280227ffd;p=thirdparty%2Fknot-resolver.git doc: started doxygen/sphinx documentation with breathe for apiref --- diff --git a/.gitignore b/.gitignore index 80b17c24c..07fe1c3b7 100644 --- a/.gitignore +++ b/.gitignore @@ -10,9 +10,11 @@ *.Plo *.swp *.d +*.db .dirstamp .libs .deps +_obj /autom4te.cache/* /config.log /config.h @@ -30,3 +32,5 @@ /aclocal.m4 /ltmain.sh /ylwrap +/doc/doxyxml +/doc/html diff --git a/CodingStyle b/CodingStyle new file mode 100644 index 000000000..09babc79b --- /dev/null +++ b/CodingStyle @@ -0,0 +1,5 @@ +# Style + +Linux kernel [coding style][lkstyle], same practices for API documentation. + +[lkstyle]: https://www.kernel.org/doc/Documentation/CodingStyle diff --git a/Makefile b/Makefile index bbe033ba7..a1be42423 100644 --- a/Makefile +++ b/Makefile @@ -5,8 +5,9 @@ include platform.mk all: info libkresolve modules kresolved install: libkresolve-install modules-install kresolved-install check: all tests -clean: libkresolve-clean modules-clean kresolved-clean tests-clean -.PHONY: all install check clean +clean: libkresolve-clean modules-clean kresolved-clean tests-clean doc-clean +doc: doc-html +.PHONY: all install check clean doc # Options ifdef COVERAGE @@ -18,6 +19,8 @@ $(eval $(call find_lib,libknot)) $(eval $(call find_lib,libknot-int)) $(eval $(call find_lib,libuv)) $(eval $(call find_lib,cmocka)) +$(eval $(call find_bin,doxygen)) +$(eval $(call find_bin,sphinx-build)) $(eval $(call find_python)) CFLAGS += $(libknot_CFLAGS) $(libuv_CFLAGS) $(cmocka_CFLAGS) $(python_CFLAGS) @@ -27,3 +30,4 @@ include lib/libkresolve.mk include daemon/kresolved.mk include modules/modules.mk include tests/tests.mk +include doc/doc.mk diff --git a/doc/Doxyfile b/doc/Doxyfile new file mode 100644 index 000000000..70af9a77c --- /dev/null +++ b/doc/Doxyfile @@ -0,0 +1,15 @@ +PROJECT_NAME = Knot DNS Resolver library +GENERATE_LATEX = NO +GENERATE_MAN = NO +GENERATE_RTF = NO +CASE_SENSE_NAMES = NO +INPUT = ../lib +QUIET = YES +JAVADOC_AUTOBRIEF = YES +AUTOLINK_SUPPORT = YES +GENERATE_HTML = NO +GENERATE_XML = YES +XML_OUTPUT = doxyxml +PREDEFINED = _GNU_SOURCE=1 +EXCLUDE_PATTERNS = *.c +OPTIMIZE_OUTPUT_FOR_C = YES diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 000000000..01b15943e --- /dev/null +++ b/doc/README.md @@ -0,0 +1,25 @@ +## Documentation + +Each directory contains a README.md with the basic information, examples and usage. +It does not however contain API documentation, which is built separately in this directory. + +### Requirements + +The code is documented with [Doxygen][doxygen] JavaDoc style, a prettified documentation +also requires [breathe][breathe] and [Sphinx][sphinx] for building sane documentation pages. +It is not however required. + +[doxygen]:http://www.stack.nl/~dimitri/doxygen/manual/index.html +[breathe]: https://github.com/michaeljones/breathe +[sphinx]: http://sphinx-doc.org/ + +You can get the extra dependencies with pip: + +```sh +pip install -U Sphinx breathe +``` + +### Building documentation + +If you satisfy the requirements, it's as easy as `make doc`, which builds the documentation in this folder. + diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 000000000..3671da59a --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,166 @@ +# -*- coding: utf-8 -*- + +import sys, os, re, subprocess + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +if os.environ.get('READTHEDOCS', None) == 'True': + subprocess.call('doxygen') + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.ifconfig', 'sphinx.ext.todo', 'breathe'] + +breathe_projects = { "libkresolve": "doxyxml" } +breathe_default_project = "libkresolve" +breathe_domain_by_extension = {"h" : "c"} + +# The suffix of source filenames. +source_suffix = '.rst' + +# General information about the project. +project = u'Knot DNS Resolver' +copyright = u'2014-2015 CZ.NIC labs' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +version = { k[0][0]: k[0][1] for k in filter(None, [re.findall(r'(MAJOR|MINOR|PATCH) := ([0-9]+)',line) for line in open('../config.mk')])} +version = '{}.{}.{}'.format(version['MAJOR'], version['MINOR'], version['PATCH']) + +# The full version, including alpha/beta/rc tags. +release = version + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' +highlight_language = 'c' +primary_domain = 'c' + +# -- 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' + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# 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'] + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'formatdoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'format.tex', u'Knot DNS Resolver', + u'CZ.NIC Labs', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'libkresolve', u'libkresolve documentation', + [u'CZ.NIC Labs'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + diff --git a/doc/contents.rst b/doc/contents.rst new file mode 100644 index 000000000..606717b26 --- /dev/null +++ b/doc/contents.rst @@ -0,0 +1,10 @@ +################# +Knot DNS Resolver +################# + +.. toctree:: + :maxdepth: 2 + + lib + daemon + diff --git a/doc/daemon.rst b/doc/daemon.rst new file mode 100644 index 000000000..96e00750c --- /dev/null +++ b/doc/daemon.rst @@ -0,0 +1,21 @@ +Knot DNS Resolver daemon +======================== + +Requirements +------------ + +* libuv_ 1.0+ (a multi-platform support library with a focus on asynchronous I/O) + +Starting the daemon +------------------- + +There is a separate resolver library in the `lib` directory, and a minimalistic daemon in +the `daemon` directory. The daemon accepts a few CLI parameters, and there's no support for configuration +right now. + +.. code-block:: bash + + $ ./daemon/kresolved -h + $ ./daemon/kresolved -a 127.0.0.1#53 + +.. _libuv: https://github.com/libuv/libuv diff --git a/doc/doc.mk b/doc/doc.mk new file mode 100644 index 000000000..dad588c81 --- /dev/null +++ b/doc/doc.mk @@ -0,0 +1,9 @@ +doc-doxygen: + @cd doc && $(doxygen_BIN) +doc-html: doc-doxygen + @cd doc && $(sphinx-build_BIN) -b html . html +doc-clean: + @rm -rf doc/doxyxml doc/*.db doc/html + +.PHONY: doc-doxygen doc-html doc-clean + diff --git a/doc/lib.rst b/doc/lib.rst new file mode 100644 index 000000000..384f6ee44 --- /dev/null +++ b/doc/lib.rst @@ -0,0 +1,30 @@ +Knot DNS Resolver library +========================= + +Requirements +------------ + +* libknot_ 2.0 (Knot DNS high-performance DNS library.) + +Overview +-------- + +Resolution plan +~~~~~~~~~~~~~~~ + +Cache +~~~~~ + +Reputation +~~~~~~~~~~ + +Modules +~~~~~~~ + +API reference +------------- + +.. doxygenindex:: + :project: libkresolve + +.. _libknot: https://gitlab.labs.nic.cz/labs/knot/tree/master/src/libknot diff --git a/help.mk b/help.mk index 6ae62fde1..a815ed7a1 100644 --- a/help.mk +++ b/help.mk @@ -11,6 +11,7 @@ info: $(info ) $(info Features) $(info --------) + $(info [$(HAS_doxygen)] API documentation (doxygen)) $(info [$(HAS_libknot)] library (libknot)) $(info [$(HAS_libknot-int)] library (libknot-int)) $(info [$(HAS_libuv)] daemon (libuv)) diff --git a/lib/README.rst b/lib/README.rst new file mode 120000 index 000000000..13050ffca --- /dev/null +++ b/lib/README.rst @@ -0,0 +1 @@ +../doc/lib.rst \ No newline at end of file diff --git a/tests/README.md b/tests/README.md new file mode 100644 index 000000000..9d21bec9b --- /dev/null +++ b/tests/README.md @@ -0,0 +1,3 @@ +## Unit tests + +## Integration tests