Command line config options

[alandefreitas]

In ci.yml, when generating the demos, we use the original mrdocs.yml file provided by Boost.URL. This is useful to generate the demos with the proper configuration for the project. However, the demo includes combinatorial variants of the multipage and generate config options. This means CI has to repeatedly edit the original mrdocs.yml so we generate the proper variants. The way we do it is:

sed -i "s/^\(\s*multipage:\s*\).*\$/\1$multipage/" $(pwd)/boost/libs/url/doc/mrdocs.yml
sed -i "s/^\(\s*generate:\s*\).*\$/\1$format/" $(pwd)/boost/libs/url/doc/mrdocs.yml

Needless to say, this is very unstable.

Doxygen

Doxygen allows users to override options specified in its configuration file using command-line arguments. This allows users to slightly customize Doxygen's behavior without modifying the configuration file itself.

To override options, the user uses the -s flag followed by the option name and its new value. Here is the syntax:

doxygen -s OPTION_NAME=VALUE

Use cases

The common Use Cases are:

• Temporary Changes: If you need to temporarily change an output directory for a single run, using a command line override is more convenient than editing the Doxyfile.
• Automation Scripts: When integrating Doxygen into build or CI/CD scripts, command line overrides allow you to customize behavior based on the environment without modifying the Doxyfile.

Some examples

Override Input Directory:

doxygen -s INPUT=/path/to/alternative/source/files

Specify Output Directory:

doxygen -s OUTPUT_DIRECTORY=/path/to/alternative/output/directory

Enable or Disable HTML Output:

doxygen -s GENERATE_HTML=NO

Set Project Name:

doxygen -s PROJECT_NAME="New Project Name"

Full Command Line Example:

doxygen -s INPUT=/new/source/path -s OUTPUT_DIRECTORY=/new/output/path -s GENERATE_HTML=NO -s PROJECT_NAME="New Project"

Technical issue

We use a YAML configuration file that, unlike Doxyfiles, allows nested object values. In this case, nested values can be referenced with ".".