scons-tool-doxyfile 0.2.0

SCons tool to generate Doxyfile for Doxygen

SCons tool to generate Doxyfile for Doxygen. The generated Doxyfile may be further used by scons_doxygen tool.

Installation

There are few ways to install this tool for your project.

From pypi

This method may be preferable if you build your project under a virtualenv. To add doxyfile tool from pypi, type (within your wirtualenv):

pip install scons-tool-loader scons-tool-doxyfile

or, if your project uses pipenv:

pipenv install --dev scons-tool-loader scons-tool-doxyfile

Alternatively, you may add this to your Pipfile

[dev-packages]
scons-tool-loader = "*"
scons-tool-doxyfile = "*"

The tool will be installed as a namespaced package sconstool.doxyfile in project’s virtual environment. You may further use scons-tool-loader to load the tool.

As a git submodule

1. Create new git repository:

   mkdir /tmp/prj && cd /tmp/prj
   touch README.rst
   git init

2. Add the scons-tool-doxyfile as a submodule:

   git submodule add git://github.com/ptomulik/scons-tool-doxyfile.git site_scons/site_tools/doxyfile

3. For python 2.x create __init__.py in site_tools directory:

   touch site_scons/site_tools/__init__.py

   this will allow to directly import site_tools.doxyfile (this may be required by other tools).

Usage example

Git-based projects

1. Copy doxygen template to src/, for example:

   mkdir src && cp site_scons/site_tools/doxyfile/Doxyfile.in src/

2. Create some source files, for example src/test.hpp:

   // src/test.hpp
   /**
    * @brief Test class
    */
   class TestClass { };

3. Write SConstruct file:

   # SConstruct
   env = Environment(tools=['doxyfile', 'doxygen'])
   SConscript('src/SConscript', exports=['env'], variant_dir='build', duplicate=0)

4. Write src/SConscript:

   # src/SConscript
   Import(['env'])
   doxyfile = env.Doxyfile( INPUT = '.', RECURSIVE = True)
   env.Doxygen(doxyfile)

5. Try it out:

   scons

   This shall create documentation under build directory.

6. Check the generated documentation (it should contain docs for TestClass under Classes tab):

   firefox build/html/index.html

Details

Module contents and description

The scons-tool-doxyfile contains these crucial files:

• __init__.py, doxyoptions.py and about.py files,

• Doxyfile.in template,

• SConstruct script, and

• this README.rst

The tool provides a Doxyfile() builder which generates Doxyfile configuration file from Doxyfile.in template. It accepts several options to customize the generated Doxyfile. The options are passed as keyword arguments to Doxyfile:

env.Doxyfile(INPUT='.', RECURSIVE=True, STRIP_FROM_INC_PATH='.', ...)

Same template may be used to generate documentation for several sub-projects by using different sets of options (and variant builds, if necessary). You may also use your own template file, instead of default Doxyfile.in shipped along with this tool.

Option types

The options Doxyfile() builder accepts are categorized into several types:

Type	Note	Example value in SConscript	Example output to Doxyfile
int	integer	3	3
str	string	‘str1’ or ‘str 2’	str1 or “str 2”
list	list	[‘a b’, False, 3]	“a b” False 3
dict	dictionary	{‘a’ : ‘A’, ‘b’ : ‘B’}	a=A b=B
bool	boolean	True or False	YES or NO
entry	ref to file or directory	‘foo’	/tmp/prj/build/foo
file	ref to file	‘bar.txt’	/tmp/prj/build/bar.txt
dir	ref to directory	‘.’	/tmp/prj/build
srcentry	ref to source file or dir	‘foo’	/tmp/prj/src/foo
srcfile	ref to source file	‘foo.txt’	/tmp/prj/src/foo.txt
srcdir	ref to source directory	‘.’	/tmp/prj/src
dualentry	ref to entry + its source	‘foo’	/tmp/prj/build/foo \ /tmp/prj/src/foo
dualfile	ref to file + its source	‘foo.txt’	/tmp/prj/build/foo.txt \ /tmp/prj/src/foo.txt
dualdir	ref to dir + its source	‘.’	/tmp/prj/build \ /tmp/prj/src
entries	list of entries	[‘foo’, ‘bar/gez’]	/tmp/prj/build/foo \ /tmp/prj/build/bar/geez
files	list of files	[‘foo’, ‘bar.txt’]	/tmp/prj/build/foo \ /tmp/prj/build/bar.txt
dirs	list of directories	[‘.’, ‘foo’]	/tmp/prj/build \ /tmp/prj/build/foo
srcentries	list of source entries	[‘.’, ‘foo’]	/tmp/prj/src \ /tmp/prj/src/foo
srcfiles	list of source files	[‘a.txt’, ‘b.txt’]	/tmp/prj/src/a.txt \ /tmp/prj/src/b.txt
srcdirs	list of source dirs	[‘.’, ‘foo’]	/tmp/prj/src \ /tmp/prj/src/foo
dualentries	list of dual entries	[‘.’, ‘foo’]	/tmp/prj/build \ /tmp/prj/src \ /tmp/prj/build/foo \ /tmp/prj/src/foo
dualfiles	list of dual files	[‘a.txt’, ‘b.txt’]	/tmp/prj/build/a.txt \ /tmp/prj/src/a.txt \ /tmp/prj/build/b.txt \ /tmp/prj/src/b.txt
dualdirs	list of dual directories	[‘.’, ‘foo’]	/tmp/prj/build \ /tmp/prj/src \ /tmp/prj/build/foo \ /tmp/prj/src/foo

An entry is a path to file or directory (undecided). For each value of type entry, file or dir a single path is outputted to Doxyfile. If relative paths are provided by user, they are assumed to be relative to a directory containing the calling SConscript. Note, that SCons will write absolute paths to Doxyfile, so you should consider using STRIP_FROM_PATH, STRIP_FROM_INC_PATH and similar options.

In variant builds, the entry, file and directory, if given as relative paths, will point to a file or subdirectory of build dir.

A srcentry, srcfile, or srcdir will generate a path pointing to a source file or directory corresponding to given file. This, of course, becomes relevant when variant builds are used.

Dual entry, file (or directory) results with a single path or two paths being emitted to Doxyfile. For variant builds, pair of paths is written to Doxyfile: the first one in build dir and the second pointing to a corresponding source file or dir.

The values written to Doxyfile are automatically quoted if they contain white spaces. For example, the hash {'a' : 'be ce'} will result with a="be ce".

Values being assigned to Doxyfile options are subject of simple validation.

Supported options

The supported options are summarized in the following table:

Option	Type	Default
ABBREVIATE_BRIEF	str
ALIASES	str
ALLEXTERNALS	bool	NO
ALPHABETICAL_INDEX	bool	YES
ALWAYS_DETAILED_SEC	bool	NO
AUTOLINK_SUPPORT	bool	YES
BINARY_TOC	bool	NO
BRIEF_MEMBER_DESC	bool	YES
BUILTIN_STL_SUPPORT	bool	NO
CALLER_GRAPH	bool	NO
CALL_GRAPH	bool	NO
CASE_SENSE_NAMES	bool	OS specific
CHM_FILE	srcfile
CHM_INDEX_ENCODING	str
CITE_BIB_FILES	files
CLANG_ASSISTED_PARSING	bool	NO
CLANG_OPTIONS	str
CLASS_DIAGRAMS	bool	YES
CLASS_GRAPH	bool	YES
COLLABORATION_GRAPH	bool	YES
COLS_IN_ALPHA_INDEX	str
COMPACT_LATEX	bool	NO
COMPACT_RTF	bool	NO
CPP_CLI_SUPPORT	bool	NO
CREATE_SUBDIRS	bool	NO
DIRECTORY_GRAPH	bool	YES
DISABLE_INDEX	bool	NO
DISTRIBUTE_GROUP_DOC	bool	NO
DOCBOOK_OUTPUT	dir
DOCSET_BUNDLE_ID	str	org.doxygen.Project
DOCSET_FEEDNAME	str	“Doxygen generated docs”
DOCSET_PUBLISHER_ID	str	org.doxygen.Publisher
DOCSET_PUBLISHER_NAME	str	Publisher
DOTFILE_DIRS	srcdirs
DOT_CLEANUP	bool	YES
DOT_FONTNAME	str	Helvetica
DOT_FONTPATH	srcdir
DOT_FONTSIZE	int	10
DOT_GRAPH_MAX_NODES	int	50
DOT_IMAGE_FORMAT	str	png
DOT_MULTI_TARGETS	bool	NO
DOT_NUM_THREADS	int	0
DOT_PATH	str
DOT_TRANSPARENT	bool	NO
DOXYFILE_ENCODING	str	UTF-8
ECLIPSE_DOC_ID	str	org.doxygen.Project
ENABLED_SECTIONS	str
ENABLE_PREPROCESSING	bool	YES
ENUM_VALUES_PER_LINE	int	4
EXAMPLE_PATH	srcdirs
EXAMPLE_PATTERNS	str
EXAMPLE_RECURSIVE	bool	NO
EXCLUDE	srcdirs
EXCLUDE_PATTERNS	str
EXCLUDE_SYMBOLS	str
EXCLUDE_SYMLINKS	bool	NO
EXPAND_AS_DEFINED	list
EXPAND_ONLY_PREDEF	bool	NO
EXTENSION_MAPPING	str
EXTERNAL_GROUPS	bool	YES
EXTERNAL_PAGES	bool	YES
EXTERNAL_SEARCH	bool	NO
EXTERNAL_SEARCH_ID	str
EXTRACT_ALL	bool	NO
EXTRACT_ANON_NSPACES	bool	NO
EXTRACT_LOCAL_CLASSES	bool	YES
EXTRACT_LOCAL_METHODS	bool	NO
EXTRACT_PACKAGE	bool	NO
EXTRACT_PRIVATE	bool	NO
EXTRACT_STATIC	bool	NO
EXTRA_PACKAGES	str
EXTRA_SEARCH_MAPPINGS	str
EXT_LINKS_IN_WINDOW	bool	NO
FILE_PATTERNS	str
FILE_VERSION_FILTER	str
FILTER_PATTERNS	dict
FILTER_SOURCE_FILES	bool	NO
FILTER_SOURCE_PATTERNS	dict
FORCE_LOCAL_INCLUDES	bool	NO
FORMULA_FONTSIZE	int	10
FORMULA_TRANSPARENT	bool	YES
FULL_PATH_NAMES	bool	YES
GENERATE_AUTOGEN_DEF	bool	NO
GENERATE_BUGLIST	bool	YES
GENERATE_CHI	bool	NO
GENERATE_DEPRECATEDLIST	bool	YES
GENERATE_DOCBOOK	bool	NO
GENERATE_DOCSET	bool	NO
GENERATE_ECLIPSEHELP	bool	NO
GENERATE_HTML	bool	YES
GENERATE_HTMLHELP	bool	NO
GENERATE_LATEX	bool	YES
GENERATE_LEGEND	bool	YES
GENERATE_MAN	bool	NO
GENERATE_PERLMOD	bool	NO
GENERATE_QHP	bool	NO
GENERATE_RTF	bool	NO
GENERATE_TAGFILE	file
GENERATE_TESTLIST	bool	YES
GENERATE_TODOLIST	bool	YES
GENERATE_TREEVIEW	bool	NO
GENERATE_XML	bool	NO
GRAPHICAL_HIERARCHY	bool	YES
GROUP_GRAPHS	bool	YES
HAVE_DOT	bool	NO
HHC_LOCATION	str
HIDE_FRIEND_COMPOUNDS	bool	NO
HIDE_IN_BODY_DOCS	bool	NO
HIDE_SCOPE_NAMES	bool	NO
HIDE_UNDOC_CLASSES	bool	NO
HIDE_UNDOC_MEMBERS	bool	NO
HIDE_UNDOC_RELATIONS	bool	YES
HTML_COLORSTYLE_GAMMA	int	80
HTML_COLORSTYLE_HUE	int	220
HTML_COLORSTYLE_SAT	int	100
HTML_DYNAMIC_SECTIONS	bool	NO
HTML_EXTRA_FILES	srcfiles
HTML_EXTRA_STYLESHEET	srcfile
HTML_FILE_EXTENSION	str	.html
HTML_FOOTER	srcfile
HTML_HEADER	srcfile
HTML_INDEX_NUM_ENTRIES	int	100
HTML_OUTPUT	str	html
HTML_STYLESHEET	srcfile
HTML_TIMESTAMP	bool	YES
IDL_PROPERTY_SUPPORT	bool	YES
IGNORE_PREFIX	str
IMAGE_PATH	srcdirs
INCLUDED_BY_GRAPH	bool	YES
INCLUDE_FILE_PATTERNS	str
INCLUDE_GRAPH	bool	YES
INCLUDE_PATH	srcdirs
INHERIT_DOCS	bool	YES
INLINE_GROUPED_CLASSES	bool	NO
INLINE_INFO	bool	YES
INLINE_INHERITED_MEMB	bool	NO
INLINE_SIMPLE_STRUCTS	bool	NO
INLINE_SOURCES	bool	NO
INPUT	srcentries
INPUT_ENCODING	str	UTF-8
INPUT_FILTER	str
INTERACTIVE_SVG	bool	NO
INTERNAL_DOCS	bool	NO
JAVADOC_AUTOBRIEF	bool	NO
LATEX_BATCHMODE	bool	NO
LATEX_BIB_STYLE	str
LATEX_CMD_NAME	str	latex
LATEX_EXTRA_FILES	srcfiles
LATEX_FOOTER	srcfile
LATEX_HEADER	srcfile
LATEX_HIDE_INDICES	bool	NO
LATEX_OUTPUT	str	latex
LATEX_SOURCE_CODE	bool	NO
LAYOUT_FILE	srcfile
LOOKUP_CACHE_SIZE	int	0
MACRO_EXPANSION	bool	NO
MAKEINDEX_CMD_NAME	str	makeindex
MAN_EXTENSION	str	.3
MAN_LINKS	bool	NO
MAN_OUTPUT	str	man
MARKDOWN_SUPPORT	bool	YES
MATHJAX_CODEFILE	srcfile
MATHJAX_EXTENSIONS	str
MATHJAX_FORMAT	str	HTML-CSS
MATHJAX_RELPATH	str	http://cdn.mathjax.org/mathjax/latest
MAX_DOT_GRAPH_DEPTH	int	0
MAX_INITIALIZER_LINES	int	30
MSCFILE_DIRS	dirs
MSCGEN_PATH	str
MULTILINE_CPP_IS_BRIEF	bool	NO
OPTIMIZE_FOR_FORTRAN	bool	NO
OPTIMIZE_OUTPUT_FOR_C	bool	NO
OPTIMIZE_OUTPUT_JAVA	bool	NO
OPTIMIZE_OUTPUT_VHDL	bool	NO
OUTPUT_DIRECTORY	dir
OUTPUT_LANGUAGE	str	English
PAPER_TYPE	str	a4
PDF_HYPERLINKS	bool	YES
PERLMOD_LATEX	bool	NO
PERLMOD_MAKEVAR_PREFIX	str
PERLMOD_PRETTY	bool	YES
PERL_PATH	str	/usr/bin/perl
PREDEFINED	list
PROJECT_BRIEF	str
PROJECT_LOGO	str
PROJECT_NAME	str	“My Project”
PROJECT_NUMBER	str
QCH_FILE	str
QHG_LOCATION	str
QHP_CUST_FILTER_ATTRS	str
QHP_CUST_FILTER_NAME	str
QHP_NAMESPACE	str
QHP_SECT_FILTER_ATTRS	str
QHP_VIRTUAL_FOLDER	str	doc
QT_AUTOBRIEF	bool	NO
QUIET	bool	NO
RECURSIVE	bool	NO
REFERENCED_BY_RELATION	bool	NO
REFERENCES_LINK_SOURCE	bool	YES
REFERENCES_RELATION	bool	NO
REPEAT_BRIEF	bool	YES
RTF_EXTENSIONS_FILE	file
RTF_HYPERLINKS	bool	NO
RTF_OUTPUT	str	rtf
RTF_STYLESHEET_FILE	file
SEARCHDATA_FILE	str	searchdata.xml
SEARCHENGINE	bool	YES
SEARCHENGINE_URL	str
SEARCH_INCLUDES	bool	YES
SEPARATE_MEMBER_PAGES	bool	NO
SERVER_BASED_SEARCH	bool	NO
SHORT_NAMES	bool	NO
SHOW_FILES	bool	YES
SHOW_INCLUDE_FILES	bool	YES
SHOW_NAMESPACES	bool	YES
SHOW_USED_FILES	bool	YES
SIP_SUPPORT	bool	NO
SKIP_FUNCTION_MACROS	bool	YES
SORT_BRIEF_DOCS	bool	NO
SORT_BY_SCOPE_NAME	bool	NO
SORT_GROUP_NAMES	bool	NO
SORT_MEMBERS_CTORS_1ST	bool	NO
SORT_MEMBER_DOCS	bool	YES
SOURCE_BROWSER	bool	NO
SOURCE_TOOLTIPS	bool	YES
STRICT_PROTO_MATCHING	bool	NO
STRIP_CODE_COMMENTS	bool	YES
STRIP_FROM_INC_PATH	srcdirs
STRIP_FROM_PATH	srcdirs
SUBGROUPING	bool	YES
TAB_SIZE	int	4
TAGFILES	str
TCL_SUBST	str
TEMPLATE_RELATIONS	bool	NO
TOC_EXPAND	bool	NO
TREEVIEW_WIDTH	int	250
TYPEDEF_HIDES_STRUCT	bool	NO
UML_LIMIT_NUM_FIELDS	int	10
UML_LOOK	bool	NO
USE_HTAGS	bool	NO
USE_MATHJAX	bool	NO
USE_MDFILE_AS_MAINPAGE	srcfile
USE_PDFLATEX	bool	YES
VERBATIM_HEADERS	bool	YES
WARNINGS	bool	YES
WARN_FORMAT	str	“$file:$line: $text”
WARN_IF_DOC_ERROR	bool	YES
WARN_IF_UNDOCUMENTED	bool	YES
WARN_LOGFILE	file
WARN_NO_PARAMDOC	bool	NO
XML_DTD	str
XML_OUTPUT	str	xml
XML_PROGRAMLISTING	bool	YES
XML_SCHEMA	str

Notes to developers

Regenerating documentation for options

If you change some options in doxyoptions.py, then you should regenerate option’s documentation in README.rst. New documentation may be generated by running:

scons -Q doc-options

After that, copy-paste the output of the above command to an appropriate place in this README.rst (note, just skip scons messages).

LICENSE

Copyright (c) 2013-2018 by Pawel Tomulik <[e-mail]>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE