Skip to content

ptomulik/scons-tool-doxyfile

Repository files navigation

scons-tool-doxyfile

PyPi package version Travis CI build status https://ci.appveyor.com/api/projects/status/github/ptomulik/scons-tool-doxyfile?svg=true

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-2020 by Paweł Tomulik <ptomulik@meil.pw.edu.pl>

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