### Run Sphinx Quickstart and Configure Build Directory

Source: https://github.com/svenevs/exhale/blob/master/docs/quickstart.rst

Initiate the Sphinx project setup using `sphinx-quickstart`. This snippet highlights the prompt for separating source and build directories, with the default 'n' (keep together) being the recommended choice.

```console
$ sphinx-quickstart
Welcome to the Sphinx 4.3.1 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: .

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: n
```

--------------------------------

### Initialize Sphinx Project Directory

Source: https://github.com/svenevs/exhale/blob/master/docs/quickstart.rst

This console command sequence demonstrates how to navigate to your repository's root and create a dedicated 'docs' directory, which is the canonical location for Sphinx documentation.

```console
$ cd /path/to/my/repo
$ mkdir docs
$ cd docs
```

--------------------------------

### Add Custom Static Files via Sphinx setup(app) Method

Source: https://github.com/svenevs/exhale/blob/master/docs/quickstart.rst

This Python snippet for `conf.py` shows how to programmatically add custom CSS and JavaScript files to a Sphinx project using the `setup(app)` method. It assumes the static files are located in the `_static` directory, which is configured via `html_static_path`. This method provides more control than direct configuration values.

```Python
# See discussion above about html_static_path, let's assume that the files
# docs/_static/custom.css and docs/_static/super_hack.js exist.
html_static_path = ["_static"]

# ... other configurations ...

def setup(app):
    app.add_css_file("custom.css")
    app.add_js_file("super_hack.js", async="async")
```

--------------------------------

### Build Sphinx Documentation with Makefile

Source: https://github.com/svenevs/exhale/blob/master/docs/quickstart.rst

Demonstrates how to use the generated Makefile to build Sphinx documentation. Replace "builder" with a supported builder like `html`, `latex`, or `linkcheck`.

```Shell
make builder
```

--------------------------------

### Compare Sphinx Project Directory Structures

Source: https://github.com/svenevs/exhale/blob/master/docs/quickstart.rst

This comparison illustrates the resulting directory layouts based on the `sphinx-quickstart` choice for separating source and build directories. It shows how `_build` (or `build`) and other core files are organized relative to `conf.py`.

```text
docs/
├── _build
│       build artifacts
│       go here
├── conf.py
├── index.rst
├── make.bat
├── Makefile
├── _static
└── _templates
```

```text
docs/
├── build
│     build artifacts
│     go here
├── make.bat
├── Makefile
└── source
    ├── conf.py
    ├── index.rst
    ├── _static
    └── _templates
```

--------------------------------

### Finalize Sphinx Project Metadata

Source: https://github.com/svenevs/exhale/blob/master/docs/quickstart.rst

Complete the `sphinx-quickstart` process by providing essential project metadata such as the project name, author names, and release version. This information is used by Sphinx to populate `conf.py` and other generated documentation.

```console
$ sphinx-quickstart
...

The project name will occur in several places in the built documentation.
> Project name: Super Project
> Author name(s): Myself ThePerson, Robotic Armistice
> Project release []: 0.1.0

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
```

--------------------------------

### Enable Breathe and Exhale Sphinx Extensions

Source: https://github.com/svenevs/exhale/blob/master/docs/quickstart.rst

This Python snippet for `conf.py` demonstrates how to add the 'breathe' and 'exhale' extensions to the `extensions` list in a Sphinx project. This is a crucial step for integrating Doxygen documentation with Sphinx using these tools.

```Python
# The `extensions` list should already be in here from `sphinx-quickstart`
extensions = [
    # there may be others here already, e.g. 'sphinx.ext.mathjax'
    'breathe',
    'exhale'
]

# Setup the breathe extension
```

--------------------------------

### Link Generated API in Sphinx toctree Directive

Source: https://github.com/svenevs/exhale/blob/master/docs/quickstart.rst

This reStructuredText snippet shows how to include the generated `library_root.rst` file, which serves as the root for the Exhale-generated API documentation, into a Sphinx `toctree` directive. This makes the API documentation discoverable and navigable within the Sphinx project.

```reStructuredText
.. toctree::
   :maxdepth: 2

   about
   api/library_root
```

--------------------------------

### Install Exhale and its Dependencies

Source: https://github.com/svenevs/exhale/blob/master/README.rst

This command installs the Exhale Sphinx extension along with all its required dependencies, including Breathe, BeautifulSoup, and lxml, using the pip package manager.

```console
$ python -m pip install exhale
```

--------------------------------

### Configure Exhale Extension in Sphinx conf.py

Source: https://github.com/svenevs/exhale/blob/master/docs/quickstart.rst

This Python snippet for `conf.py` demonstrates how to configure the Exhale extension for Sphinx. It sets up `breathe_projects` to specify Doxygen XML output, defines the default project, and configures `exhale_args` for output paths, root file names, and Doxygen execution. It also sets the primary domain and highlight language to C++.

```Python
breathe_projects = {
    "My Project": "./_doxygen/xml"
}
breathe_default_project = "My Project"

# Setup the exhale extension
exhale_args = {
    # These arguments are required
    "containmentFolder":     "./api",
    "rootFileName":          "library_root.rst",
    "doxygenStripFromPath":  "..",
    # Heavily encouraged optional argument (see docs)
    "rootFileTitle":         "Library API",
    # Suggested optional arguments
    "createTreeView":        true,
    # TIP: if using the sphinx-bootstrap-theme, you need
    # "treeViewIsBootstrap": true,
    "exhaleExecutesDoxygen": true,
    "exhaleDoxygenStdin":    "INPUT = ../include"
}

# Tell sphinx what the primary language being documented is.
primary_domain = 'cpp'

# Tell sphinx what the pygments highlight language should be.
highlight_language = 'cpp'
```

--------------------------------

### Minimal Doxygen File and Struct Documentation Example in C++

Source: https://github.com/svenevs/exhale/blob/master/docs/mastering_doxygen.rst

A complete C++ example showing how to document a file and a struct within it using Doxygen, including the \file command and explicit file association for the struct, ensuring both appear in the generated documentation.

```cpp
#pragma once
/** \\file */

/**
 * \\struct thing file.h directory/file.h
 *
 * \\brief The documentation about the thing.
 */
 struct thing {
    /// The thing that makes the thing.
    thing() {}
 };
```

--------------------------------

### Run Exhale Testing Suite with Tox

Source: https://github.com/svenevs/exhale/blob/master/docs/testing.rst

Instructions to set up and execute the entire Exhale test suite using `tox`. This command installs `tox` and then runs all defined test environments in isolated virtual environments, handling dependencies like `pytest` automatically.

```Console
$ cd /path/to/exhale
$ pip install tox
$ tox
```

--------------------------------

### Configure CMake for OpenCppCoverage on MSVC

Source: https://github.com/svenevs/exhale/blob/master/testing/projects/CMakeLists.txt

Handles the setup for OpenCppCoverage on MSVC. It first checks for the `OpenCppCoverage.exe` executable and throws a fatal error if not found, providing installation instructions. It then populates the `OPEN_CPP_COVERAGE_SOURCES` list by converting source directories to native paths, preparing them for the OpenCppCoverage command.

```CMake
elseif (MSVC)
  # Require user (or AppVeyor script) have already installed OpenCppCoverage.exe.
  find_program(OPEN_CPP_COVERAGE_EXE OpenCppCoverage.exe)
  if (OPEN_CPP_COVERAGE_EXE STREQUAL "OPEN_CPP_COVERAGE_EXE-NOTFOUND")
    message(FATAL_ERROR
      "OpenCppCoverage.exe not found, is it in your $PATH?  You can install it "
      "with Chocolatey: `choco install opencppcoverage`.  Alternatively, follow "
      "the instructions here: https://github.com/OpenCppCoverage/OpenCppCoverage"
    )
  endif()

  # Populate a list of --sources to supply to OpenCppCoverage.
  foreach (dir ${OPEN_CPP_COVERAGE_SOURCE_LIST})
    file(TO_NATIVE_PATH "${dir}" native_path)
    list(APPEND OPEN_CPP_COVERAGE_SOURCES "--sources \"${native_path}\"")
  endforeach()
```

--------------------------------

### Example Usage of add_open_cpp_coverage_source_dirs Macro

Source: https://github.com/svenevs/exhale/blob/master/testing/projects/CMakeLists.txt

This is an example demonstrating how the `add_open_cpp_coverage_source_dirs` macro, which is expected to be defined elsewhere, would be used in a subdirectory. It appends specified source directories (e.g., 'include', 'src') from the current source directory to the `OPEN_CPP_COVERAGE_SOURCE_LIST` for OpenCppCoverage.

```CMake
add_open_cpp_coverage_source_dirs(include src)
```

--------------------------------

### Add Custom Clean Target to Sphinx Makefile

Source: https://github.com/svenevs/exhale/blob/master/docs/quickstart.rst

This Makefile snippet demonstrates how to add a custom `clean` target to the Sphinx-generated Makefile. This target removes the Doxygen XML output directory (`_doxygen/`) and the Exhale-generated API documentation folder (`api/`), ensuring a thorough cleanup of build artifacts. It's crucial to use TAB characters for indentation in Makefiles.

```Makefile
.PHONY: help Makefile clean

clean:
	rm -rf _doxygen/ api/
	@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
```

--------------------------------

### Common Doxygen Documentation Commands Reference

Source: https://github.com/svenevs/exhale/blob/master/docs/mastering_doxygen.rst

A reference guide to commonly used Doxygen commands for adding detailed documentation to various code constructs. It covers commands for linking, brief descriptions, parameters, return values, exceptions, and explicit control over documenting structs, functions, and more.

```APIDOC
Doxygen Command Reference:
- \ref: Add link to another item being documented.
- \brief: Add brief documentation to a given construct.
- \param: Add documentation for a specific parameter.
- \tparam: Add documentation for a specific template parameter.
- \throw: Add documentation for a specific exception that can be thrown.
- \return: Add documentation for the return value.
- Explicit Control Over Constructs:
  - \struct: To document a struct.
  - \union: To document a union.
  - \enum: To document an enum type.
  - \fn: To document a function.
  - \var: To document a variable or typedef or enum value.
  - \def: To document a #define.
  - \typedef: To document a typedef.
  - \file: To document a file.
  - \namespace: To document a namespace.
```

--------------------------------

### Link to a Directory in reStructuredText

Source: https://github.com/svenevs/exhale/blob/master/docs/usage.rst

This reStructuredText example demonstrates how to link to a generated directory document using the `:ref:` role. The linking mechanism is identical to files, using the `dir_` prefix and converting path separators to single underscores.

```rst
:ref:`dir_include_outer_dir_inner`
```

--------------------------------

### Documenting Exhale Core Configs Tests

Source: https://github.com/svenevs/exhale/blob/master/docs/testing/tests.rst

Documents the `testing.tests.configs` module, which contains tests related to Exhale's core configuration functionalities, ensuring proper setup and parsing.

```APIDOC
.. automodule:: testing.tests.configs
   :members:
```

--------------------------------

### Link to a File in reStructuredText

Source: https://github.com/svenevs/exhale/blob/master/docs/usage.rst

This reStructuredText example illustrates how to link to a generated file document using the `:ref:` role. It shows the `file_` prefix and how path separators are converted to single underscores in the generated link.

```rst
:ref:`file_include_outer_dir_inner_file.hpp`
```

--------------------------------

### Define and Iterate Exhale Sub-Projects in CMake

Source: https://github.com/svenevs/exhale/blob/master/testing/projects/CMakeLists.txt

Initializes the `EXHALE_PROJECTS` list with various sub-project names, including C and C++ examples. It conditionally appends `cpp_fortran_mixed` if the build is not on Windows or MSVC. The script then iterates through this list, adding each project as a subdirectory to the current CMake build.

```CMake
set(EXHALE_PROJECTS
  c_maths
  cpp_func_overloads
  cpp_long_names
  cpp_dir_underscores
  cpp_nesting
  cpp_pimpl
  "cpp with spaces"
)
# At this time I care not to figure out how to actually get a functioning fortran
# compiler setup to work with Visual Studio.  Maybe if Microsoft ever cares enough to
# provide legitimate support for this, I may decide to actually test this.
if (NOT WIN32 AND NOT MSVC)
  list(APPEND EXHALE_PROJECTS cpp_fortran_mixed)
endif()

foreach (proj ${EXHALE_PROJECTS})
  add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/${proj})
endforeach()
```

--------------------------------

### C++ Code Listing Example Output

Source: https://github.com/svenevs/exhale/blob/master/docs/mastering_doxygen.rst

Shows the rendered output of a C++ code block defined using the `.. code-block:: cpp` directive in reStructuredText. This demonstrates how C++ code is displayed with syntax highlighting.

```cpp
// This code is highlighted using the cpp lexer
void foo() { /* ... */ }
```

--------------------------------

### Documenting a C++ Class with Doxygen and File Association

Source: https://github.com/svenevs/exhale/blob/master/docs/mastering_doxygen.rst

An example demonstrating how to document a C++ class using Doxygen's \class command, explicitly associating it with its header file path to ensure correct hierarchy in generated documentation.

```cpp
/**
 * \\class MyClassName include.h path/include.h
 *
 *  Docs for MyClassName
 */
```

--------------------------------

### Link to a Namespace in reStructuredText

Source: https://github.com/svenevs/exhale/blob/master/docs/usage.rst

This reStructuredText example demonstrates how to link to a generated namespace document using the `:ref:` role. It shows the specific format for the reference, including the `namespace_` prefix and the use of double underscores for namespace separators.

```rst
:ref:`namespace_foo__bar__baz`
```

--------------------------------

### Configure Exhale Root API Document Generation

Source: https://github.com/svenevs/exhale/blob/master/docs/usage.rst

This Python snippet demonstrates how to configure the `exhale_args` dictionary to define the output path and title for the root API document generated by Exhale. Keys like `containmentFolder`, `rootFileName`, and `rootFileTitle` control the file's location and its primary heading.

```python
exhale_args = {
    "containmentFolder": "./api",
    "rootFileName": "library_root.rst",
    "rootFileTitle": "Library API"
    # ... other arguments ...
}
```

--------------------------------

### Pin Documentation Requirements for Python 3.5

Source: https://github.com/svenevs/exhale/blob/master/README.rst

For projects requiring Python 3.5 support, pin the specific versions of Sphinx, Breathe, and Exhale in your documentation requirements file to ensure compatibility. Note that Sphinx and Breathe should be installed before Exhale.

```text
sphinx>=2.0
breathe>=4.13.0
exhale<0.3.0
```

--------------------------------

### Pin Documentation Requirements for Python 2.7

Source: https://github.com/svenevs/exhale/blob/master/README.rst

To support Python 2.7, specific versions of Sphinx, Breathe, and Exhale must be pinned in the documentation requirements file. It is crucial that Sphinx and Breathe appear and are installed before Exhale.

```text
sphinx==1.8.5
breathe==4.12.0
exhale<0.3.0
```

--------------------------------

### Setup CMake Targets for gcovr XML and HTML Coverage (Unix)

Source: https://github.com/svenevs/exhale/blob/master/testing/projects/CMakeLists.txt

Configures CMake custom targets for generating code coverage reports using `gcovr` on Unix-like systems. It creates `coverage-xml` for Cobertura XML output and `coverage-html` for local HTML reports, both depending on the `exhale-projects-unit-tests` executable.

```CMake
if (UNIX)
  setup_target_for_coverage_gcovr_xml(
    NAME coverage-xml
    EXECUTABLE $<TARGET_FILE:exhale-projects-unit-tests>
    DEPENDENCIES exhale-projects-unit-tests
  )
  setup_target_for_coverage_gcovr_html(
    NAME coverage-html
    EXECUTABLE $<TARGET_FILE:exhale-projects-unit-tests>
    DEPENDENCIES exhale-projects-unit-tests
  )
```

--------------------------------

### Add Custom Entries to bs4_objects.txt for Intersphinx

Source: https://github.com/svenevs/exhale/blob/master/docs/_intersphinx/README.md

Provides examples of lines to manually add to the `bs4_objects.txt` file. These entries define custom intersphinx references for specific BeautifulSoup classes and methods, enabling them to be linked within Sphinx documentation.

```text
bs4.BeautifulSoup           py:class  1 index.html#beautifulsoup -
bs4.BeautifulSoup.get_text  py:method 1 index.html#get-text      -
bs4.element.Tag             py:class  1 index.html#tag           -
```

--------------------------------

### reStructuredText Linking Syntax for C++ Elements in Sphinx

Source: https://github.com/svenevs/exhale/blob/master/docs/usage.rst

Demonstrates common reStructuredText syntax for linking to C++ classes, methods, members, and functions within a Sphinx project, assuming 'primary_domain = 'cpp'' is set in 'conf.py'. This allows for direct linking without needing to prefix with 'cpp:'.

```reStructuredText
:class:`namespace::ClassName`
:func:`namespace::ClassName::methodName`
:member:`namespace::ClassName::mMemberName`
:func:`namespace::funcName`
```

--------------------------------

### Exhale Internal Logic for Special Case Link Generation

Source: https://github.com/svenevs/exhale/blob/master/docs/usage.rst

This Python code snippet from Exhale's internal `initializeNodeFilenameAndLink` function illustrates how unique IDs and link names are generated for 'dir', 'file', and 'namespace' nodes. It shows the string replacement logic for colons, path separators, and spaces to form valid link identifiers.

```python
SPECIAL_CASES = ["dir", "file", "namespace"]
if node.kind in SPECIAL_CASES:
    if node.kind == "file":
        unique_id = node.location
    else:
        unique_id = node.name

    unique_id = unique_id.replace(":", "_").replace(os.sep, "_").replace(" ", "_")

# ... later on ...
if node.kind in SPECIAL_CASES:
    node.link_name = "{kind}_{id}".format(kind=node.kind, id=unique_id)
```

--------------------------------

### Build and Upload Python Package to PyPI

Source: https://github.com/svenevs/exhale/blob/master/UPLOAD_NOTES.md

This snippet provides the console commands to prepare a Python package for distribution and then upload it to PyPI. It uses `tox` to build the source distribution and universal wheel into the `dist/` folder, and `twine` to upload the generated artifacts. Ensure your `~/.pypirc` file is correctly configured with your PyPI username, or specify it directly to `twine`.

```console
# Build the source distribution and universal wheel
# saved into dist/ folder
tox -e dist

# Upload!
twine upload dist/*
```

--------------------------------

### Example Exhale Internal Link Anchor in reStructuredText

Source: https://github.com/svenevs/exhale/blob/master/docs/usage.rst

This reStructuredText snippet demonstrates the format of an Exhale internal link anchor as it appears in a generated `.rst` file. The `.. _` prefix defines the link's name, which can then be referenced using `:ref:` directives without the leading underscore.

```rst
.. _exhale_class_somecrazy_thing:

Class ``somecrazy_thing``
=========================
```

--------------------------------

### Documenting C++/Fortran Mixed Project Module

Source: https://github.com/svenevs/exhale/blob/master/docs/testing/projects.rst

Configures Sphinx to generate API documentation for the `testing.projects.cpp_fortran_mixed` module, demonstrating documentation for projects with mixed C++ and Fortran source code. All public members are included.

```APIDOC
Module: testing.projects.cpp_fortran_mixed
  Purpose: Documents all public members of this module.
```

--------------------------------

### Link to Exhale Root API Document in reStructuredText

Source: https://github.com/svenevs/exhale/blob/master/docs/usage.rst

This reStructuredText example demonstrates how to create a hyperlink to the top of the generated root API document. It highlights the components of the link: the hyperlink text, the relative path to the HTML file, the anchor point derived from the root file title, and the required trailing underscore.

```rst
Please see the `full Library API <api/library_root.html#library-api>`_
```

--------------------------------

### Documenting C++ PIMPL Project Module

Source: https://github.com/svenevs/exhale/blob/master/docs/testing/projects.rst

Configures Sphinx to generate API documentation for the `testing.projects.cpp_pimpl` module, specifically for projects utilizing the Pointer-to-Implementation (PIMPL) idiom in C++. All public members are included.

```APIDOC
Module: testing.projects.cpp_pimpl
  Purpose: Documents all public members of this module.
```

--------------------------------

### Configure C Project Library and Tests with CMake

Source: https://github.com/svenevs/exhale/blob/master/testing/projects/c_maths/CMakeLists.txt

This CMakeLists.txt defines a C project named 'c-maths'. It sets the minimum required CMake version, adds a static library 'c-maths' with specified public header and private source files, and configures its public include directories. It also sets up a test target 'exhale-projects-unit-tests' by adding its source and linking it against the 'c-maths' library via an interface target. Finally, it includes a command for C++ code coverage.

```CMake
cmake_minimum_required(VERSION 3.13 FATAL_ERROR)
project(c-maths LANGUAGES C)

# Add the c-maths library
add_library(c-maths "")
target_sources(c-maths
  PUBLIC
    ${CMAKE_CURRENT_SOURCE_DIR}/include/c_maths.h
  PRIVATE
    ${CMAKE_CURRENT_SOURCE_DIR}/src/c_maths.c
)
target_include_directories(c-maths
  PUBLIC
    ${CMAKE_CURRENT_SOURCE_DIR}/include
)

# Add the tests and link against the c-maths library.
target_sources(exhale-projects-unit-tests
  PUBLIC
    ${CMAKE_CURRENT_SOURCE_DIR}/src/tests.cpp
)
target_link_libraries(exhale-projects-tests-interface
  INTERFACE
    c-maths
)

add_open_cpp_coverage_source_dirs(include src)
```

--------------------------------

### Documenting Top-Level Testing Projects Module

Source: https://github.com/svenevs/exhale/blob/master/docs/testing/projects.rst

Configures Sphinx to generate comprehensive API documentation for the `testing.projects` module, including all its public members. This serves as the entry point for documenting the entire test suite.

```APIDOC
Module: testing.projects
  Purpose: Documents all public members of this module.
```

--------------------------------

### Clean and Rebuild Sphinx HTML Documentation

Source: https://github.com/svenevs/exhale/blob/master/docs/_intersphinx/README.md

Executes Sphinx commands to clean the build directory and rebuild the HTML documentation, ensuring that the newly generated `objects.inv` file is recognized and applied.

```console
$ make clean html
```

--------------------------------

### Constructing Full Doxygen Input in Exhale (Python)

Source: https://github.com/svenevs/exhale/blob/master/docs/reference/configs.rst

This Python code illustrates how Exhale constructs the complete Doxygen input string. It demonstrates the order in which Exhale's default configurations, user-specified configurations from `exhaleDoxygenStdin`, and internal settings (like output directory and path stripping) are combined to form the final input sent to Doxygen.

```python
# doxy_dir is the parent directory of what you specified in
# `breathe_projects[breathe_default_project]` in `conf.py`
internal_configs = textwrap.dedent('''
    # Tell doxygen to output wherever breathe is expecting things
    OUTPUT_DIRECTORY       = {out}
    # Tell doxygen to strip the path names (RTD builds produce long abs paths...)
    STRIP_FROM_PATH        = {strip}
'''.format(out=doxy_dir, strip=configs.doxygenStripFromPath))

# The configurations you specified
external_configs = textwrap.dedent(configs.exhaleDoxygenStdin)

# The full input being sent
full_input = "{base}\n{external}\n{internal}\n\n".format(
    base=configs.DEFAULT_DOXYGEN_STDIN_BASE,
    external=external_configs,
    internal=internal_configs
)
```

--------------------------------

### reStructuredText Admonition: Danger Directive

Source: https://github.com/svenevs/exhale/blob/master/docs/mastering_doxygen.rst

Provides an example of a 'danger' admonition in reStructuredText, which is used for critical alerts or super-warnings. Its visual representation is theme-dependent.

```rst
.. danger::

   This is a danger (aka super-warning)!
```

--------------------------------

### Exhale Sphinx Build Execution Flow

Source: https://github.com/svenevs/exhale/blob/master/docs/reference.rst

Outlines the simplified execution flow of Exhale within the Sphinx build process, detailing how Sphinx loads extensions, triggers events, and when Exhale performs Doxygen execution and reStructuredText document generation.

```APIDOC
Execution Flow (Simplified):
1. Sphinx reads `conf.py`, loads `extensions` (breathe, exhale).
2. Each extension is `setup`:
   - Exhale requests notification of `builder-inited` event (first event with populated configurations).
   - Note: Exhale must complete document generation before `env-get-outdated`.
3. Rest of `conf.py` is processed.
4. Exhale launches:
   - If configured, executes Doxygen.
   - Generates all reStructuredText documents.
```

--------------------------------

### Documenting C Maths Project Module

Source: https://github.com/svenevs/exhale/blob/master/docs/testing/projects.rst

Configures Sphinx to generate API documentation for the `testing.projects.c_maths` module, which likely contains C language mathematical functions. All public members of this module will be included.

```APIDOC
Module: testing.projects.c_maths
  Purpose: Documents all public members of this module.
```

--------------------------------

### Python Module: testing.base API Reference

Source: https://github.com/svenevs/exhale/blob/master/docs/testing/base.rst

Comprehensive API documentation for the `testing.base` Python module, including its functions and base classes used for setting up and running tests within the Exhale project. It details the `make_default_config` function, `ExhaleTestCaseMetaclass`, and `ExhaleTestCase`.

```APIDOC
Module: testing.base
  Description: Base module for testing utilities in the Exhale project.

  Function: make_default_config()
    Description: Creates a default configuration object for testing purposes.

  Class: ExhaleTestCaseMetaclass
    Description: Metaclass for Exhale test cases. It is designed to handle the documentation of members and special members for test classes.
    Members: All public and special members are documented.

  Class: ExhaleTestCase
    Description: Base class for Exhale test cases. Provides common setup and teardown functionalities, and utilities for writing tests.
    Members: All public and special members are documented.
```

--------------------------------

### reStructuredText Admonition: Note Directive

Source: https://github.com/svenevs/exhale/blob/master/docs/mastering_doxygen.rst

Demonstrates how to create a 'note' admonition in reStructuredText. Admonitions display special blocks of text, and their appearance depends on the Sphinx HTML theme. This example shows the basic syntax for a note.

```rst
.. note::

   This is a note!
```

--------------------------------

### Set Minimum CMake Version

Source: https://github.com/svenevs/exhale/blob/master/testing/projects/cpp_dir_underscores/CMakeLists.txt

Specifies the minimum required version of CMake for the project. This ensures compatibility and enables modern CMake features. If the installed CMake version is older, it will result in a fatal error.

```CMake
cmake_minimum_required(VERSION 3.13 FATAL_ERROR)
```

--------------------------------

### Documenting C++ Function Overloads Project Module

Source: https://github.com/svenevs/exhale/blob/master/docs/testing/projects.rst

Configures Sphinx to generate API documentation for the `testing.projects.cpp_func_overloads` module, specifically designed to test the documentation of C++ functions with multiple overloads. All public members are included.

```APIDOC
Module: testing.projects.cpp_func_overloads
  Purpose: Documents all public members of this module.
```

--------------------------------

### reStructuredText Code Listing: code-block Directive

Source: https://github.com/svenevs/exhale/blob/master/docs/mastering_doxygen.rst

Explains how to use the `.. code-block::` directive to display code listings with syntax highlighting. This example shows the reStructuredText syntax for embedding a C++ code block within documentation.

```rst
.. code-block:: cpp

   // This code is highlighted using the cpp lexer
   void foo() { /* ... */ }
```

--------------------------------

### Exhale Utils Module API

Source: https://github.com/svenevs/exhale/blob/master/docs/reference.rst

Details the `exhale.utils` module, providing various helper methods. These utilities include consistent formatting, colorized error reporting, and serialization of Exhale configurations, which is necessary for Sphinx's environment pickling.

```APIDOC
Module: exhale.utils
Purpose: Provides helper methods for formatting, error reporting, and configuration serialization.
Utilities:
  - Consistent formatting.
  - Colorized error reporting.
  - Serialization of Exhale configurations (for Sphinx environment).
```

--------------------------------

### Initialize CMake Project for C++

Source: https://github.com/svenevs/exhale/blob/master/testing/projects/cpp_long_names/CMakeLists.txt

Sets the minimum required CMake version and defines the project name along with the enabled languages (C++). This is the foundational setup for the CMake build system.

```CMake
cmake_minimum_required(VERSION 3.13 FATAL_ERROR)
project(cpp-long-names LANGUAGES CXX)
```

--------------------------------

### Generated reStructuredText Root API Heading

Source: https://github.com/svenevs/exhale/blob/master/docs/usage.rst

This reStructuredText snippet shows the H1 heading that Exhale generates for the root API document, based on the `rootFileTitle` configuration. It illustrates the basic structure of the generated RST file.

```rst
Library API
===========

Other stuff generated by Exhale...
```

--------------------------------

### Configure C++ PIMPL Library and Tests with CMake

Source: https://github.com/svenevs/exhale/blob/master/testing/projects/cpp_pimpl/CMakeLists.txt

This CMake script sets up the 'cpp-pimpl' library, specifying its header and source files. It also defines a test executable 'exhale-projects-unit-tests' and links it against the 'cpp-pimpl' library, ensuring proper build and test execution. Finally, it includes a command to add source directories for OpenCppCoverage.

```CMake
cmake_minimum_required(VERSION 3.13 FATAL_ERROR)
project(cpp-pimpl LANGUAGES CXX)

# Add the cpp-pimpl library
add_library(cpp-pimpl "")
target_sources(cpp-pimpl
  PUBLIC
    ${CMAKE_CURRENT_SOURCE_DIR}/include/pimpl/planet.hpp
    ${CMAKE_CURRENT_SOURCE_DIR}/include/pimpl/earth.hpp
    ${CMAKE_CURRENT_SOURCE_DIR}/include/pimpl/jupiter.hpp
  PRIVATE
    ${CMAKE_CURRENT_SOURCE_DIR}/src/earth.cpp
    ${CMAKE_CURRENT_SOURCE_DIR}/src/jupiter.cpp
)
target_include_directories(cpp-pimpl
  PUBLIC
    ${CMAKE_CURRENT_SOURCE_DIR}/include
)

# Add the tests and link against the cpp-pimpl library.
target_sources(exhale-projects-unit-tests
  PUBLIC
    ${CMAKE_CURRENT_SOURCE_DIR}/src/tests.cpp
)
target_link_libraries(exhale-projects-tests-interface
  INTERFACE
    cpp-pimpl
)

add_open_cpp_coverage_source_dirs(include src)
```

--------------------------------

### Initialize CMake Project and Check for Windows Support

Source: https://github.com/svenevs/exhale/blob/master/testing/projects/cpp_fortran_mixed/CMakeLists.txt

This snippet sets the minimum required CMake version, defines the project name, and specifies the languages used (C, C++, Fortran). It also includes a fatal error check to prevent compilation on Windows platforms, indicating that the library is not configured for Windows support.

```CMake
cmake_minimum_required(VERSION 3.13 FATAL_ERROR)
project(cpp-fortran-mixed LANGUAGES C CXX Fortran)

if (WIN32 OR MSVC)
  message(FATAL_ERROR "The cpp-fortran-mixed library is not configured for windows support.")
endif()
```

--------------------------------

### Override Flake8 Linter Flags with Tox

Source: https://github.com/svenevs/exhale/blob/master/docs/testing.rst

Example of passing specific command-line arguments (e.g., `--ignore XYYY`) to a linter like `flake8` when running it through `tox`. The `--` separator ensures arguments are forwarded to the environment's command.

```Console
tox -e flake8 -- --ignore XYYY
```

--------------------------------

### Documenting C++ Directory Underscores Project Module

Source: https://github.com/svenevs/exhale/blob/master/docs/testing/projects.rst

Configures Sphinx to generate API documentation for the `testing.projects.cpp_dir_underscores` module, testing the documentation of projects where directory names contain underscores. All public members are included.

```APIDOC
Module: testing.projects.cpp_dir_underscores
  Purpose: Documents all public members of this module.
```

--------------------------------

### API Reference for Module: exhale.utils

Source: https://github.com/svenevs/exhale/blob/master/docs/reference/utils.rst

Provides the main API documentation entry for the `exhale.utils` module, which contains various utility functions and classes for the Exhale project.

```APIDOC
Module: exhale.utils
```

--------------------------------

### Python Code Listing Example Output from Indented Block

Source: https://github.com/svenevs/exhale/blob/master/docs/mastering_doxygen.rst

Illustrates the rendered output of a Python code snippet created using the indented code block syntax in reStructuredText. This method automatically highlights the code based on Sphinx's language detection.

```python
def foo():
    pass
```

--------------------------------

### Documenting C++ Nesting Project Module

Source: https://github.com/svenevs/exhale/blob/master/docs/testing/projects.rst

Configures Sphinx to generate API documentation for the `testing.projects.cpp_nesting` module, which contains deeply nested C++ structures to test documentation generation for complex hierarchies. All public members are included.

```APIDOC
Module: testing.projects.cpp_nesting
  Purpose: Documents all public members of this module.
```

--------------------------------

### Download Catch2 Single-Include Header

Source: https://github.com/svenevs/exhale/blob/master/testing/projects/CMakeLists.txt

This command downloads the Catch2 single-include header file from its GitHub repository. The downloaded file is placed into a specific include directory within the current binary directory, making it available for compilation.

```CMake
file(
  DOWNLOAD
    https://raw.githubusercontent.com/catchorg/Catch2/v2.x/single_include/catch2/catch.hpp
    ${CMAKE_CURRENT_BINARY_DIR}/include/catch2/catch.hpp
)
```

--------------------------------

### C++ Conditional Compilation for Doxygen Skipping

Source: https://github.com/svenevs/exhale/blob/master/docs/mastering_doxygen.rst

An example of using the `DOXYGEN_SHOULD_SKIP_THIS` preprocessor symbol in C++ code. This allows developers to exclude specific code blocks, such as problematic forward declarations, from Doxygen's parsing, preventing incorrect documentation generation or errors.

```cpp
#if !defined(DOXYGEN_SHOULD_SKIP_THIS)
    // forward declarations in particular will make Doxygen think that the
    // class is defined in a different file!

```

--------------------------------

### ExhaleTestCase Base Class for Project Tests

Source: https://github.com/svenevs/exhale/blob/master/docs/testing.rst

API documentation for `testing.base.ExhaleTestCase`, the base class for creating new project-specific tests in Exhale. It outlines class-level variables and methods that automatically handle `pytest` fixtures and `sphinx` bootstrapping.

```APIDOC
testing.base.ExhaleTestCase:
  Description: Base class for creating new project-specific tests that need to generate output files.
  Class-level variable:
    test_project: str
      Description: The name of the new project folder in `testing/projects/`.
  Methods:
    test_{something}():
      Description: Test methods where the configuration is applied, `sphinx` is bootstrapped, and `*.rst` files generated by `exhale` are available in the specified output directory. The `sphinx` application is available as `self.app`.
```

--------------------------------

### Configure Unit Test Target and Link Against Mixed-Language Library

Source: https://github.com/svenevs/exhale/blob/master/testing/projects/cpp_fortran_mixed/CMakeLists.txt

This snippet defines the source files for the `exhale-projects-unit-tests` target. It then links the `exhale-projects-tests-interface` target against the `cpp-fortran-mixed` library using an `INTERFACE` dependency, making the mixed-language library's public components available for the test suite.

```CMake
target_sources(exhale-projects-unit-tests
  PUBLIC
    ${CMAKE_CURRENT_SOURCE_DIR}/src/tests.cpp
)
target_link_libraries(exhale-projects-tests-interface
  INTERFACE
    cpp-fortran-mixed
)
```

--------------------------------

### Example reStructuredText Contents Directive Configuration

Source: https://github.com/svenevs/exhale/blob/master/docs/reference/configs.rst

Illustrates the default `.. contents::` directive used by Exhale for Namespace and File documents. This configuration includes the `:local:` option to limit the table of contents to the current page's remainder and `:backlinks: none` to disable backlinks.

```rst
.. contents:: Contents
   :local:
   :backlinks: none
```

--------------------------------

### Exhale Deploy Module API Reference

Source: https://github.com/svenevs/exhale/blob/master/docs/reference/deploy.rst

Documents the `exhale.deploy` module, including functions for Doxygen execution and library API generation. This module is central to Exhale's documentation generation process, providing utilities for configuration validation and XML output.

```APIDOC
Module: exhale.deploy
  Description: Core module for deploying Exhale documentation, handling Doxygen execution and library API generation.

  Functions:
    _generate_doxygen()
      Description: Internal function responsible for executing Doxygen to generate documentation.

    _valid_config()
      Description: Internal function used to validate the Exhale configuration settings.

    generateDoxygenXML()
      Description: Public function that orchestrates the generation of Doxygen XML output.

    explode()
      Description: Function dedicated to the generation of library API documentation.
```

--------------------------------

### Exhale Deploy Module API

Source: https://github.com/svenevs/exhale/blob/master/docs/reference.rst

Describes the `exhale.deploy` module, responsible for assisting in Doxygen documentation creation and 'exploding' the documentation into various reStructuredText documents. The `explode` function is crucial for triggering graph creation.

```APIDOC
Module: exhale.deploy
Purpose: Orchestrates Doxygen execution and reStructuredText document generation.
Data:
  - exhaleExecutesDoxygen: Configuration flag for Doxygen execution.
Functions:
  - explode(): Triggers the creation of the documentation graph and document generation.
```

--------------------------------

### Documenting C++ With Spaces Project Tests

Source: https://github.com/svenevs/exhale/blob/master/docs/testing/tests.rst

Documents the `testing.tests.cpp_with_spaces` module, specifically for testing C++ projects where file or directory names contain spaces, ensuring proper path handling.

```APIDOC
.. automodule:: testing.tests.cpp_with_spaces
   :members:
```

--------------------------------

### Configure CMake Project for C++ and Manage Test Sources/Includes

Source: https://github.com/svenevs/exhale/blob/master/testing/projects/cpp_nesting/CMakeLists.txt

This CMake snippet initializes a project by setting the minimum required CMake version and defining a C++ project. It then specifies source files for a unit test target and configures interface include directories, ensuring that the project's C++ components and tests are properly built and linked. Additionally, it includes a command to add directories for C++ code coverage analysis.

```CMake
cmake_minimum_required(VERSION 3.13 FATAL_ERROR)
project(cpp-nesting LANGUAGES CXX)

target_sources(exhale-projects-unit-tests
  PUBLIC
    ${CMAKE_CURRENT_SOURCE_DIR}/src/tests.cpp
)
target_include_directories(exhale-projects-tests-interface
  INTERFACE
    ${CMAKE_CURRENT_SOURCE_DIR}/include
)

add_open_cpp_coverage_source_dirs(include src)
```

--------------------------------

### Example C++ Doxygen Comment with reStructuredText Alias

Source: https://github.com/svenevs/exhale/blob/master/docs/mastering_doxygen.rst

Illustrates how to use the `\rst` and `\endrst` Doxygen aliases within C++ code comments. This allows embedding complex reStructuredText content, such as mathematical equations and grid tables, directly into Doxygen documentation, overriding Doxygen's default Markdown processing.

```cpp
/**
 * \file
 *
 * \brief This file does not even exist in the real world.
 *
 * \rst
 * There is a :math:`N^2` environment for reStructuredText!
 *
 * +-------------------+-------------------+
 * | Grid Tables       | Are Beautiful     |
 * +===================+===================+
 * | Easy to read      | In code and docs  |
 * +-------------------+-------------------+
 * | Exceptionally flexible and powerful   |
 * +-------+-------+-------+-------+-------+
 * | Col 1 | Col 2 | Col 3 | Col 4 | Col 5 |
 * +-------+-------+-------+-------+-------+
 *
 * \endrst
 */
```

--------------------------------

### Migrating Doxygen \ref to Sphinx Domain Links

Source: https://github.com/svenevs/exhale/blob/master/docs/usage.rst

When embedding Doxygen output in a verbatim reStructuredText environment, Doxygen's \ref command for cross-referencing becomes inactive. Instead, Sphinx's domain-specific linking syntax, such as :class:, must be used to create valid links to classes, functions, or other targets.

```Doxygen
\ref namespace::ClassName
```

```Sphinx/reStructuredText
:class:`namespace::ClassName`
```

--------------------------------

### Run Specific Tox Test Environments

Source: https://github.com/svenevs/exhale/blob/master/docs/testing.rst

Commands to selectively run different test environments configured in `tox`. This includes executing only Python unit tests, linting checks, building Sphinx documentation (HTML or linkcheck), providing fine-grained control over the testing process.

```Console
tox -e py
    Run the python unit tests.

tox -e flake8
    Run the lint tests.

tox -e docs
    Build the sphinx documentation using the *html* builder (in nitpicky mode).  You can
    view the generated html website with ``open .tox/docs/tmp/html/index.html``.

tox -e linkcheck
    Build the sphinx documentation using the *linkcheck* builder.
```

--------------------------------

### Configure C++ Project with Spaces using CMake

Source: https://github.com/svenevs/exhale/blob/master/testing/projects/cpp with spaces/CMakeLists.txt

This snippet provides the full CMake configuration for a C++ project. It sets the minimum CMake version, defines a C++ project, adds a library with sources and include paths that contain spaces, and links unit tests to this library. It also includes a custom command for C++ coverage.

```CMake
cmake_minimum_required(VERSION 3.13 FATAL_ERROR)
project(cpp-with-spaces LANGUAGES CXX)

# Add the cpp-with-spaces library
add_library(cpp-with-spaces "")
target_sources(cpp-with-spaces
  PUBLIC
    "${CMAKE_CURRENT_SOURCE_DIR}/include/with spaces/with spaces.hpp"
  PRIVATE
    "${CMAKE_CURRENT_SOURCE_DIR}/src/with spaces.cpp"
)
target_include_directories(cpp-with-spaces
  PUBLIC
    ${CMAKE_CURRENT_SOURCE_DIR}/include
)

# Add the tests and link against the c-maths library.
target_sources(exhale-projects-unit-tests
  PUBLIC
    ${CMAKE_CURRENT_SOURCE_DIR}/src/tests.cpp
)
target_link_libraries(exhale-projects-tests-interface
  INTERFACE
    cpp-with-spaces
)

add_open_cpp_coverage_source_dirs(include src)
```

--------------------------------

### Generating Exhale Internal Link Names in Python

Source: https://github.com/svenevs/exhale/blob/master/docs/usage.rst

This Python snippet illustrates how Exhale constructs unique internal link names. It uses the node's `refid` and `kind` attributes, prefixed with `exhale_`, to create a distinct identifier for anchor points, preventing conflicts with Doxygen's `refid` used by Breathe.

```python
unique_id = node.refid

# ... later on ...
node.link_name = "exhale_{kind}_{id}".format(kind=node.kind, id=unique_id)
```

--------------------------------

### Visualize Exhale Documentation Generation Flow with Graphviz

Source: https://github.com/svenevs/exhale/blob/master/docs/reference.rst

This Graphviz DOT code defines a directed graph that illustrates the internal execution flow of the Exhale documentation generator. It shows the sequence of operations, including Sphinx build, Exhale initialization, configuration application, reStructuredText document generation, and Sphinx parsing/generation steps, along with their interdependencies and component responsibilities.

```DOT
digraph exe_flow {
    /* Global graph configurations, node and edge styling */
    nodesep=1;
    rankdir="LR";
    node [width=2, height=2, style=filled, fontname="Courier"];

    /* Rank declarations (e.g. keeps init and ext next to each other) */
    build;
    {rank=same; init; ext}
    {rank=same; apply_configs; cfg;}
    {rank=same; explode; rst; sphinx_parse; sphinx_gen}

    /* Edge declarations */
    build -> init;

    init -> ext [dir=back, style=dashed];
    init -> apply_configs;

    apply_configs -> cfg [dir=back, style=dashed];
    apply_configs -> explode;

    explode      -> rst;
    rst          -> sphinx_parse;
    sphinx_parse -> sphinx_gen;

    /* Node specific styling */
    build [
        shape=rectangle, style="rounded,filled", fillcolor="#c4c4c4",
        label="make html"
    ];

    init [
        shape=octagon, fillcolor="#90cc7f", label="exhale/__init__.py\nsetup(app)"
    ];
    ext [
        shape=rectangle, style="rounded,filled", fontname="Times New Roman",
        label="conf.py had 'exhale'\nin the 'extensions' list"
    ];

    apply_configs [
        shape=octagon, fillcolor="#a2ddf9",
        label="exhale/configs.py\napply_sphinx_configurations"
    ];
    cfg [
        shape=rectangle, style="rounded,filled", fontname="Times New Roman",
        label="Exhale reads configs in\n'exhale_args' dictionary from conf.py"
    ];

    explode [
        shape=octagon, fillcolor="#f7f389", label="exhale/deploy.py\nexplode"
    ];
    rst [
        shape=doubleoctagon, fillcolor="#f7f389", fontname="Times New Roman",
        label="Exhale generates the\nreStructuredText documents."
    ];
    sphinx_parse [
        shape=rectangle, style="rounded,filled", fontname="Times New Roman",
        label="Sphinx searches for / parses\nreStructuredText found in\nthe source directory."
    ];
    sphinx_gen [
        shape=rectangle, style="rounded,filled", fontname="Times New Roman",
        label="Sphinx generates your website!"
    ];
}
```

--------------------------------

### Documenting C++ Fortran Mixed Project Tests

Source: https://github.com/svenevs/exhale/blob/master/docs/testing/tests.rst

Documents the `testing.tests.cpp_fortran_mixed` module, covering tests for projects that combine C++ and Fortran code, ensuring interoperability.

```APIDOC
.. automodule:: testing.tests.cpp_fortran_mixed
   :members:
```

--------------------------------

### Example reStructuredText for Manual Exhale Document Inclusion

Source: https://github.com/svenevs/exhale/blob/master/docs/reference/configs.rst

This reStructuredText snippet illustrates how to manually compose a root Sphinx document by including Exhale-generated files. It demonstrates the use of `.. include::` directives to incorporate various hierarchy views (page, class, file) and the unabridged API, which is useful when `rootFileName` is set to 'EXCLUDE' for custom document structuring.

```rst
=======================
Some Title You Provided
=======================

.. include:: page_index.rst.include

.. include:: page_view_hierarchy.rst.include

.. include:: class_view_hierarchy.rst.include

.. include:: file_view_hierarchy.rst.include

.. include:: unabridged_api.rst.include
```