Setting up Documentation

Currently doxygen is being used. At a later point in time we want to re-evaluate standardese. See also the issue on the concepts ts.

Another option would be doxypress which supposedly supports more modern C++.

Installation

1. Install Doxygen on your system if not installed.
2. create a directory, e.g. ~/devel/seqan3-doc/
3. create two subdirectories ~/devel/seqan3-doc/user and ~/devel/seqan3-doc/dev
4. in each directory create the directory output
5. in the dev and user directory, create a my-doxygen-file by copying the configurations below into a new file (user and dev respectively, adapt the paths)
6. running doxygen my-doxygen-file in the dev or user directory will create the html documentation in the output subfolder

It might be helpful to filter the output for warnings, e.g. doxygen 2>&1 | grep warning to see if you forgot or broke something.

Configuration

Documentation for users of SeqAn3 shall be generated with these custom settings:

PROJECT_NAME           = "SeqAn3"
INPUT                  = /where/is/seqan3/include
STRIP_FROM_PATH        = /where/is/seqan3/include
STRIP_FROM_INC_PATH    = /where/is/seqan3/include
EXAMPLE_PATH           = /where/is/seqan3/
OUTPUT_DIRECTORY       = /where/should/it/go
RECURSIVE              = YES
DISABLE_INDEX          = YES
GENERATE_TREEVIEW      = YES
INLINE_INHERITED_MEMB  = YES
HAVE_DOT               = YES
COLLABORATION_GRAPH    = NO
TEMPLATE_RELATIONS     = YES
DOT_IMAGE_FORMAT       = svg
INTERACTIVE_SVG        = YES
ENABLE_PREPROCESSING   = YES
MACRO_EXPANSION        = YES
EXPAND_ONLY_PREDEF     = YES
SORT_BRIEF_DOCS        = YES
PREDEFINED             = "CEREAL_SERIALIZE_FUNCTION_NAME=serialize" \
                         "CEREAL_LOAD_FUNCTION_NAME=load" \
                         "CEREAL_SAVE_FUNCTION_NAME=save" \
                         "CEREAL_LOAD_MINIMAL_FUNCTION_NAME=load_minimal" \
                         "CEREAL_SAVE_MINIMAL_FUNCTION_NAME=save_minimal" \
                         "SEQAN3_DOXYGEN_ONLY(x)= x"

EXTENSION_MAPPING   = .no_extension=C++
FILE_PATTERNS       = *

For the user documentation add:

EXCLUDE_SYMBOLS        = detail
PREDEFINED             += NDEBUG

For the developer documentation instead add:

ENABLED_SECTIONS       = DEV
EXTRACT_PRIVATE        = YES