scons-tool-doxyfile

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:

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:

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