From 7bd7053aa5289706de4eac01bdede21ee9201810 Mon Sep 17 00:00:00 2001 From: Snaipe Date: Sun, 21 Feb 2016 17:09:46 +0100 Subject: [PATCH] Integrated doxygen into sphinx docs --- doc/Doxyfile | 26 +++++++++++++------------- doc/_static/style.css | 7 +++++++ doc/_templates/page.html | 3 +++ doc/conf.py | 17 ++++++++++++++++- doc/requirements.txt | 1 + 5 files changed, 40 insertions(+), 14 deletions(-) create mode 100644 doc/_static/style.css create mode 100644 doc/_templates/page.html create mode 100644 doc/requirements.txt diff --git a/doc/Doxyfile b/doc/Doxyfile index 9acc537..7b04dd1 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -58,7 +58,7 @@ PROJECT_LOGO = # entered, it will be relative to the location where doxygen was started. If # left blank the current directory will be used. -OUTPUT_DIRECTORY = ./doc/doxygen +OUTPUT_DIRECTORY = # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub- # directories (in 2 levels) under the output directory of each output format and @@ -152,7 +152,7 @@ FULL_PATH_NAMES = YES # will be relative from the directory where doxygen is started. # This tag requires that the tag FULL_PATH_NAMES is set to YES. -STRIP_FROM_PATH = +STRIP_FROM_PATH = ../include # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the # path mentioned in the documentation of a class, which tells the reader which @@ -161,7 +161,7 @@ STRIP_FROM_PATH = # specify the list of include paths that are normally passed to the compiler # using the -I flag. -STRIP_FROM_INC_PATH = +STRIP_FROM_INC_PATH = ../include # If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but # less readable) file names. This can be useful is your file systems doesn't @@ -177,7 +177,7 @@ SHORT_NAMES = NO # description.) # The default value is: NO. -JAVADOC_AUTOBRIEF = NO +JAVADOC_AUTOBRIEF = YES # If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first # line (until the first dot) of a Qt-style comment as the brief description. If @@ -185,7 +185,7 @@ JAVADOC_AUTOBRIEF = NO # requiring an explicit \brief command for a brief description.) # The default value is: NO. -QT_AUTOBRIEF = NO +QT_AUTOBRIEF = YES # The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make doxygen treat a # multi-line C++ special comment block (i.e. a block of //! or /// comments) as @@ -705,7 +705,7 @@ CITE_BIB_FILES = # messages are off. # The default value is: NO. -QUIET = NO +QUIET = YES # The WARNINGS tag can be used to turn on/off the warning messages that are # generated to standard error (stderr) by doxygen. If WARNINGS is set to YES @@ -771,7 +771,7 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = ./include/criterion +INPUT = ../include # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses @@ -802,7 +802,7 @@ FILE_PATTERNS = # be searched for input files as well. # The default value is: NO. -RECURSIVE = +RECURSIVE = YES # The EXCLUDE tag can be used to specify files and/or directories that should be # excluded from the INPUT source files. This way you can easily exclude a @@ -811,7 +811,7 @@ RECURSIVE = # Note that relative paths are relative to the directory from which doxygen is # run. -EXCLUDE = +EXCLUDE = ../include/criterion/internal/ # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded @@ -1041,7 +1041,7 @@ IGNORE_PREFIX = # If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output # The default value is: YES. -GENERATE_HTML = YES +GENERATE_HTML = NO # The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of @@ -1585,7 +1585,7 @@ EXTRA_SEARCH_MAPPINGS = # If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output. # The default value is: YES. -GENERATE_LATEX = YES +GENERATE_LATEX = NO # The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of @@ -1865,7 +1865,7 @@ MAN_LINKS = NO # captures the structure of the code including all documentation. # The default value is: NO. -GENERATE_XML = NO +GENERATE_XML = YES # The XML_OUTPUT tag is used to specify where the XML pages will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of @@ -1873,7 +1873,7 @@ GENERATE_XML = NO # The default directory is: xml. # This tag requires that the tag GENERATE_XML is set to YES. -XML_OUTPUT = xml +XML_OUTPUT = doxyxml # If the XML_PROGRAMLISTING tag is set to YES, doxygen will dump the program # listings (including syntax highlighting and cross-referencing information) to diff --git a/doc/_static/style.css b/doc/_static/style.css new file mode 100644 index 0000000..caca612 --- /dev/null +++ b/doc/_static/style.css @@ -0,0 +1,7 @@ +.breatheparameterlist li p { + display: inline; +} + +.breatheenumvalues li p { + display: inline; +} diff --git a/doc/_templates/page.html b/doc/_templates/page.html new file mode 100644 index 0000000..fb70918 --- /dev/null +++ b/doc/_templates/page.html @@ -0,0 +1,3 @@ +{% extends "!page.html" %} + +{% set css_files = css_files + ["_static/style.css"] %} diff --git a/doc/conf.py b/doc/conf.py index 216e17e..9731c78 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -13,10 +13,25 @@ sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "_ext")) # If your documentation needs a minimal Sphinx version, state it here. #needs_sphinx = '1.0' +# hack for readthedocs to cause it to run doxygen first +# https://github.com/rtfd/readthedocs.org/issues/388 +on_rtd = os.environ.get('READTHEDOCS', None) == 'True' +if on_rtd: + from subprocess import call + 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 = [] +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.todo', + 'sphinx.ext.viewcode', + 'breathe', +] + +breathe_projects = { "criterion-doxygen": "doxyxml/" } +breathe_default_project = "criterion-doxygen" # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 0000000..cd6467e --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1 @@ +breathe