Exhale

https://github.com/svenevs/exhale
Admin
Exhale is an automatic C++ library API documentation generator that uses Doxygen, Sphinx, and...
Tokens:33,465
Snippets:255
Trust Score:6.6
License:BSD-3-Clause
Update:1 month ago
Show doc for...
Tokens:
Raw
### Configure setup(app) in conf.py

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

Demonstrates using the setup(app) method in conf.py to add custom CSS and JS files to a Sphinx project.

```py
# 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")
```

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

### Run sphinx-quickstart utility

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

Initiating the Sphinx quickstart process and selecting the directory structure option.

```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
```

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

### Minimal \struct example for directory/file.h

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

Minimal working example for a header in a subdirectory: \struct thing file.h directory/file.h makes Doxygen associate struct thing with directory/file.h. The \file command documents the header, and the constructor is documented with a /// comment.

```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() {}
 };
```

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

### Install Exhale with pip

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

Install Exhale and its dependencies using pip. This is the standard installation method from PyPI.

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

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

### Run Exhale tests with tox

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

Install tox and run the full test suite. Requires only tox; additional dependencies like pytest are installed automatically in a virtual environment.

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

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

### Sphinx directory structure comparison

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

Comparison of directory layouts when choosing 'n' (keep together) versus 'y' (separate source and build) during setup.

```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
```

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

### Setup coverage targets for UNIX

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

Configures gcovr XML and HTML coverage targets for the exhale-projects-unit-tests executable on UNIX systems.

```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
  )
elseif (MSVC)
```

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

### Sphinx .. tip:: admonition example

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

Sphinx admonition for a tip. No arguments or specifications are needed; keep a blank line between the directive and the text. Display depends on the html_theme chosen in conf.py.

```rst
   .. tip::

      This is a tip!
```

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

### Setup Code Coverage for Non-Windows

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

Configures GCOVR coverage flags for non-Windows platforms before adding subdirectories.

```cmake
if (NOT WIN32)
  # See ${CMAKE_BINARY_DIR}/cmake/CodeCoverage.cmake, this trims the local genhtml report
  set(COVERAGE_GCOVR_EXCLUDES
    "'/usr/*'"
    "'${CMAKE_BINARY_DIR}/*'"
  )
  include(CodeCoverage)
  append_coverage_compiler_flags()
endif()
```

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

### Set containmentFolder in exhale_args

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

Example of specifying the containmentFolder key in exhale_args. The key name matches the configuration attribute name.

```python
exhale_args = {
    "containmentFolder": "./api",
    # other required entries here
}
```

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

### Find and verify OpenCppCoverage.exe

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

Locates the OpenCppCoverage executable using find_program and aborts the build if it is not found. Installation can be done via Chocolatey or official instructions.

```CMake
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()
```

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

### CMake project setup and environment checks

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

Initial CMake configuration for the cpp-long-names project. Requires CMake 3.13 or later and CXX language. On non-Windows systems, it finds Python and Git, failing with an error if either is missing.

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

# Windows cannot handle the full test case because of its antiquated filesystem.
if (NOT WIN32)
  # Will re-use the methods defined in testing/tests/cpp_long_names.py to generate the
  # full test case directory paths.
  find_program(PYTHON_EXECUTABLE python)
  if (PYTHON_EXECUTABLE STREQUAL PYTHON_EXECUTABLE-NOTFOUND)
    message(FATAL_ERROR "This project requires python in order to generate the full test case.")
  endif()

  # Using git rev-parse to make life easier to find the cpp_long_names.py test case.
  find_program(GIT_EXECUTABLE git)
  if (GIT_EXECUTABLE STREQUAL GIT_EXECUTABLE-NOTFOUND)
    message(FATAL_ERROR "This project requires git in order to generate the full test case.")
  endif()

  # Acquire the full path to the repository root and create the path to where the
  # cpp_long_names.py file lives.
  execute_process(
    COMMAND         ${GIT_EXECUTABLE} rev-parse --show-toplevel
    RESULT_VARIABLE GIT_EXIT_CODE
    OUTPUT_VARIABLE REPOSITORY_ROOT
    ERROR_VARIABLE  GIT_FAILURE_MESSAGE
  )
  if (GIT_EXIT_CODE)
    message(FATAL_ERROR "Non-zero exit code of [${GIT_EXIT_CODE}] executing 'git rev-parse --show-toplevel'. ${GIT_FAILURE_MESSAGE}")
  elseif (REPOSITORY_ROOT MATCHES "^$")
    message(FATAL_ERROR "Impossible empty string result of 'git rev-parse --show-toplevel'...")
  endif()
  # Remove trailing newline from command-line output.
  string(REGEX REPLACE "\n" "" REPOSITORY_ROOT "${REPOSITORY_ROOT}")
  set(CPP_LONG_NAMES_PY "${REPOSITORY_ROOT}/testing/tests/cpp_long_names.py")
  if (NOT EXISTS "${CPP_LONG_NAMES_PY}")
    message(FATAL_ERROR "Could not find the file [${CPP_LONG_NAMES_PY}]!")
  endif()

  # Create a script to call the function to make directories.  If only there was
  # textwrap.dedent(...) in CMake x0
  string(CONCAT GENERATE_ABSURD_SCRIPT_CONTENTS
    "import os\n"
    "import sys\n"
    "\n"
    "\n"
    "if __name__ == '__main__':\n"
    "    try:\n"
    "        # Make it so we can import 'exhale' and 'testing'\n"
    "        repository_root = os.path.abspath('${REPOSITORY_ROOT}')\n"
    "        sys.path.insert(0, repository_root)\n"
    "\n"
    "        from testing.tests import cpp_long_names\n"
    "        cpp_long_names.create_absurd_directory_structure()\n"
    "\n"
    "        # Print out what we just made verify it was created in CMake.\n"
    "        sys.stdout.write(os.path.join(\n"
    "            cpp_long_names.ABSURD_DIRECTORY_PATH, 'a_file.hpp'\n"
    "        ))\n"
    "        sys.exit(0)\n"
    "    except Exception as e:\n"
    "        sys.stderr.write('Critical error trying to make the absurd path: {}'.format(e))\n"
    "        sys.exit(1)\n"
  )
  set(GENERATE_ABSURD_SCRIPT "${CMAKE_CURRENT_BINARY_DIR}/prepare_cpp_long_names.py")

  # Only generate this once to prevent re-builds.
  if (NOT EXISTS ${GENERATE_ABSURD_SCRIPT})
    file(WRITE "${GENERATE_ABSURD_SCRIPT}" "${GENERATE_ABSURD_SCRIPT_CONTENTS}")

    # Call the script to generate the absurd path.
    execute_process(
      COMMAND ${PYTHON_EXECUTABLE} ${GENERATE_ABSURD_SCRIPT}
      RESULT_VARIABLE GENERATE_ABSURD_SCRIPT_EXIT_CODE
      OUTPUT_VARIABLE ABSURD_FILE_PATH
      ERROR_VARIABLE  GENERATE_ABSURD_SCRIPT_FAILURE_MESSAGE
    )
    if (GENERATE_ABSURD_SCRIPT_EXIT_CODE)
      message(FATAL_ERROR "Could not generate the absurd file path. ${GENERATE_ABSURD_SCRIPT_FAILURE_MESSAGE}")
    endif()
  endif()
endif()
```

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

### Directory link reference syntax

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

Example of the reStructuredText reference syntax for a directory, which follows the same path separator replacement rules as files.

```rst
.. node.kind
..    |-|
:ref:`dir_include_outer_dir_inner`
```

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

### Sphinx .. note:: admonition example

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

Sphinx admonition for a short note. No arguments or specifications are needed; keep a blank line between the directive and the text. Display depends on the html_theme chosen in conf.py.

```rst
   .. note::

      This is a note!
```

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

### File include link reference syntax

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

Example of the reStructuredText reference syntax for a file, noting that path separators are replaced with a single underscore.

```rst
..  node.kind
..    |--|
:ref:`file_include_outer_dir_inner_file.hpp`
```

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

### Namespace link reference syntax

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

Example of the reStructuredText reference syntax for a namespace, noting that two underscores are used between namespaces.

```rst
..    node.kind
..    |-------|
:ref:`namespace_foo__bar__baz`
..                 ||   ||
..           Two underscores between namespaces!
..           from: replace(":", "_")
```

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

### Sphinx .. warning:: admonition example

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

Sphinx admonition for a warning. No arguments or specifications are needed; keep a blank line between the directive and the text. Display depends on the html_theme chosen in conf.py.

```rst
   .. warning::

      This is a warning!
```

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

### Override PREDEFINED in exhaleDoxygenStdin

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

Example of setting exhaleDoxygenStdin with INPUT and PREDEFINED. Using `=` instead of `+=` overrides the default PREDEFINED section; Exhale will warn but continue.

```python
import textwrap
exhale_args = {
    # ... required args ...
    "exhaleExecutesDoxygen": True,
    "exhaleDoxygenStdin": textwrap.dedent('''
        INPUT      = ../include
        # Using `=` instead of `+=` overrides
        PREDEFINED = FOO="12"
    ''')
}
```

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

### Reference Exhale Internal Links

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

Example of how to manually reference an Exhale-generated anchor point in reStructuredText.

```rst
.. _exhale_class_somecrazy_thing:

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

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

### Sphinx .. danger:: admonition example

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

Sphinx admonition for a danger (super-warning). No arguments or specifications are needed; keep a blank line between the directive and the text. Display depends on the html_theme chosen in conf.py.

```rst
   .. danger::

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

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

### reStructuredText directive syntax with specifications

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

Shows the required three-space indentation for reStructuredText directives. Directives start with two dots, a space, the directive name, and two colons; a blank line separates specifications from the directive text.

```rst
   .. directive:: primary argument
      :specifications:

      There is exactly *ONE* blank line between the specifications and the text that is
      a part of the directive.
```

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

### Default tox envlist in tox.ini

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

Default tox environment list: runs Python unit tests and flake8 linting. The Python version used is the interpreter tox was installed with.

```ini
[testenv]
envlist = py, flake8
```

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

### Build documentation using Makefile

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

Use the generated Makefile to build documentation by specifying the desired builder.

```bash
make builder
```

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

### Create documentation directory

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

Commands to create and enter the documentation directory within a repository.

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

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

### Configure project metadata

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

Entering project name, author, and release version during the sphinx-quickstart configuration.

```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.
```

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

### Build distribution and upload with tox and twine

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

Builds the source distribution and universal wheel into the dist/ folder using tox -e dist, then uploads all artifacts to PyPI with twine upload dist/*. Ensure ~/.pypirc has a username under [pypi] or pass it directly to twine.

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

# Upload!
$ twine upload dist/*
```

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

### Test Configuration and Coverage

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

Configures the unit tests, links them to the library, and enables OpenCppCoverage.

```cmake
# 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)
```

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

### Configure conf.py for Exhale and Breathe

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

Add the extensions to the list and define the project-specific settings for Breathe and Exhale.

```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
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'
```

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

### Initialize OpenCppCoverage Source List for MSVC

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

Creates an empty list for OpenCppCoverage sources when using the MSVC compiler.

```cmake
if (MSVC)
  set(OPEN_CPP_COVERAGE_SOURCE_LIST ) # Create empty list, modified in child projects
endif()
```

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

### CMake Configuration for cpp-pimpl

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

Defines the project, adds the library with its public and private sources, and sets up include directories.

```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
)
```

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

### Combine Doxygen stdin configurations

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

Shows how Exhale combines its default Doxygen stdin, your exhaleDoxygenStdin, and internal output/strip settings. The defaults are sent first, then your configurations, then the output directory and strip from path.

```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
)
```

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

### Use DOXYGEN_SHOULD_SKIP_THIS and DOXYGEN_DOCUMENTATION_BUILD

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

Use these preprocessor macros to prevent Doxygen from parsing specific code blocks or to force inclusion of platform-specific code during documentation generation.

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

// platform specific code
#if defined(__APPLE__) || defined(DOXYGEN_DOCUMENTATION_BUILD)
    /// This method is only needed on Apple
    void they_think_they_are_special();

    /**
     * This definition changes depending on the platform, but we can just
     * document it once.
     *
     * - Apple: ``12``
     * - Linux: ``21``
     * - Windows: ``0``
     */
    #define SOME_CONSTANT 12
#elif defined(__linux__)
    #define SOME_CONSTANT 21
#else
    #define SOME_CONSTANT 0
#endif
```

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

### Define PREDEFINED preprocessor symbols

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

Sets additional preprocessor symbols to assist in building the correct version of the documentation.

```make
# extra defs for to help with building the _right_ version of the docs
PREDEFINED  = DOXYGEN_DOCUMENTATION_BUILD
PREDEFINED += DOXYGEN_SHOULD_SKIP_THIS
```

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

### Define code using the double-colon indentation method

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

Demonstrates the alternative syntax for code blocks using two colons and four-space indentation.

```rst
This is a paragraph::

    def foo():
        pass
```

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

### Convert bs4_objects.txt back to zlib inventory

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

After adding new lines to bs4_objects.txt, convert it back to the zlib-compressed inventory file.

```console
$ sphobjinv convert zlib bs4_objects.txt bs4_objects.inv
```

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

### Clean and rebuild Sphinx documentation

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

Runs 'make clean html' to force a full rebuild so the doctree index is updated with the new intersphinx inventory.

```console
$ make clean html
```

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

### Build OpenCppCoverage source list

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

Populates a list of --sources arguments for OpenCppCoverage from the OPEN_CPP_COVERAGE_SOURCE_LIST variable. Converts each path to native format and appends as a quoted source option.

```CMake
foreach (dir ${OPEN_CPP_COVERAGE_SOURCE_LIST})
    file(TO_NATIVE_PATH "${dir}" native_path)
    list(APPEND OPEN_CPP_COVERAGE_SOURCES "--sources \"${native_path}\"")
  endforeach()
```

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

### Configure Main Unit Testing Executable

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

Defines the primary test executable and links it to the interface library.

```cmake
add_executable(exhale-projects-unit-tests
  ${CMAKE_CURRENT_BINARY_DIR}/src/main.cpp
)
target_link_libraries(exhale-projects-unit-tests
  PRIVATE
    exhale-projects-tests-interface
)
```

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

### Project Directory Structure

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

The expected file structure after Exhale processes the project.

```text
my_project/
├── docs/
│   ├── api/
│   │   └── library_root.rst
│   │
│   ├── conf.py
│   ├── index.rst
│   │
│   └── _doxygen/
│       └── xml/
│           └── index.xml
│
├── include/
│   └── common.hpp
│
└── src/
    └── common.cpp
```

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

### Configure intersphinx_mapping in conf.py

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

Sets the intersphinx mapping for 'bs4' to point to the local inventory file instead of the online one.

```py
intersphinx_mapping = {
   'bs4':    ('https://www.crummy.com/software/BeautifulSoup/bs4/doc/', "_intersphinx/bs4_objects.inv")
}
```

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

### Configure breathe_projects for Breathe

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

Required Breathe configuration mapping project names to Doxygen XML output paths. Relative paths are relative to conf.py.

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

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

### CMake configuration for c-maths library and tests

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

Defines the c-maths library target with public header and private source, sets public include directories, adds test sources to exhale-projects-unit-tests, links c-maths to exhale-projects-tests-interface, and registers coverage source directories.

```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)
```

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

### Convert objects.inv to plain text with sphobjinv

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

Converts the binary inventory file to a human-readable plain text file using the sphobjinv convert command.

```console
$ sphobjinv convert plain bs4_objects.inv bs4_objects.txt
```

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

### Add test sources and include directories

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

Adds the test source file and include directory to the exhale-projects-unit-tests target. Uses target_sources and target_include_directories with PUBLIC and INTERFACE scopes respectively.

```cmake
# "Header only library": add tests and include the directory
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)
```

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

### Define EXHALE_PROJECTS and add subdirectories

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

Sets the list of projects to be validated and iterates through them to add subdirectories. It conditionally includes fortran projects on non-Windows platforms.

```cmake
set(EXHALE_PROJECTS
  c_maths
  cpp_func_overloads
  cpp_long_names
  cpp_dir_underscores
  cpp_nesting
  cpp_pimpl
  "cpp with spaces"
)
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()
```

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

### Configure PREDEFINED macros in Doxygen

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

Use the PREDEFINED configuration option to tell Doxygen how to expand custom macros during the documentation build process.

```make
PREDEFINED += NAMESPACE_BEGIN(nanogui)="namespace nanogui {"
PREDEFINED += NAMESPACE_END(nanogui)="}"
```

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

### Pin dependencies for Python 3.5

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

Pin Sphinx, Breathe, and Exhale versions for Python 3.5 support. Use exhale<0.3.0.

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

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

### Configure exhale_args for root file generation

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

Define the containment folder, root file name, and root file title in your exhale_args configuration to determine the generated file path and H1 heading.

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

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

### Reference BeautifulSoup classes and methods in RST

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

Shows how to use the custom intersphinx mapping in RST documentation to link to BeautifulSoup classes and methods.

```rst
- See :class:`bs4.BeautifulSoup`
- See :meth:`bs4.BeautifulSoup.get_text`
- See :class:`bs4.element.Tag`
```

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

### Pin dependencies for Python 2.7

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

Pin Sphinx, Breathe, and Exhale versions for Python 2.7 support. Use exhale<0.3.0.

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

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

### Handle special cases for namespaces, files, and directories

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

Logic used by Exhale to generate unique IDs for special compounds that do not have standard Breathe directives or Sphinx C++ domain equivalents.

```py
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(" ", "_")
```

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

### Use makeCustomSpecificationsMapping in exhale_args

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

Use exhale.utils.makeCustomSpecificationsMapping to convert the specificationsForKind function into a mapping for the customSpecificationsMapping configuration. The parameter is the function itself, not its return value.

```python
# Use exhale's utility function to transform `specificationsForKind`
# defined above into something Exhale can use
from exhale import utils
exhale_args = {
    # ... required arguments / other configs ...
    "customSpecificationsMapping": utils.makeCustomSpecificationsMapping(
        specificationsForKind
    )
}
```

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

### CMakeLists.txt for cpp-func-overloads

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

CMake configuration for the cpp-func-overloads project. Defines the library with public headers and private sources, sets include directories, adds a test source, links the library to the test interface, and registers coverage source directories.

```cmake
cmake_minimum_required(VERSION 3.13 FATAL_ERROR)
project(cpp-func-overloads LANGUAGES CXX)

# Add the cpp-func-overloads library
add_library(cpp-func-overloads "")
target_sources(cpp-func-overloads
  PUBLIC
    ${CMAKE_CURRENT_SOURCE_DIR}/include/overload/overload.hpp
    ${CMAKE_CURRENT_SOURCE_DIR}/include/overload/operators.hpp
  PRIVATE
    ${CMAKE_CURRENT_SOURCE_DIR}/src/overload.cpp
    ${CMAKE_CURRENT_SOURCE_DIR}/src/operators.cpp
)
target_include_directories(cpp-func-overloads
  PUBLIC
    ${CMAKE_CURRENT_SOURCE_DIR}/include
)

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

add_open_cpp_coverage_source_dirs(include src)
```

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

### Define coverage-html target

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

Adds a custom target that runs OpenCppCoverage with HTML export for local viewing. Invoke with cmake --build . --target coverage-html.

```CMake
add_custom_target(
    coverage-html
    COMMAND ${OPEN_CPP_COVERAGE_EXE} ${OPEN_CPP_COVERAGE_SOURCES}
      --working_dir "\"${PROJECT_BINARY_DIR}\""
      --export_type html:coverage_html
      -- $<TARGET_FILE:exhale-projects-unit-tests>
    WORKING_DIRECTORY ${PROJECT_BINARY_DIR}
    DEPENDS exhale-projects-unit-tests
  )
```

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

### Define Interface Library for Project Dependencies

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

Creates an interface library to manage include directories for sub-project dependencies.

```cmake
add_library(exhale-projects-tests-interface INTERFACE)
target_include_directories(exhale-projects-tests-interface
  INTERFACE
    ${CMAKE_CURRENT_BINARY_DIR}/include
)
```

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

### Create a reStructuredText link to the root API

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

Use a relative path and the anchor derived from the root file title to link to the generated API document.

```rst
..                         html, not rst! ----------vv
..                                                 vvvv
Please see the `full Library API <api/library_root.html#library-api>`_
..              |--------------|  |-------------------| |---------|  |
..                     1                    2                3       4
```

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

### Set breathe_default_project for Exhale

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

Required Breathe configuration to select the default project for Exhale when multiple projects are available.

```python
breathe_default_project = "My Project"
```

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

### CMake configuration for cpp-with-spaces library

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

Defines the library target with sources that include paths containing spaces. Sets public include directories and links the library to the test interface. Also adds test sources and coverage directories.

```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)
```

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

### Exhale Configuration Arguments

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

Configuration arguments for Exhale and Breathe that users must set in their Sphinx conf.py file.

```APIDOC
## breathe_projects (dict)

### Description
Maps project names to Doxygen XML output paths. This is a required configuration for Breathe, which Exhale uses to locate the Doxygen XML output for the project.

### Type
dict

### Required
Yes

### Keys
- **project name** (str) - The name of the project.

### Values
- **path** (str) - Absolute or relative path to the Doxygen XML output. Relative paths are relative to `conf.py`.

### Example
```py
breathe_projects = {
    "My Project": "./_doxygen/xml"
}
```

## breathe_default_project (str)

### Description
Specifies the default project for Breathe, which determines the project Exhale will generate when multiple projects are available. This is a required configuration.

### Type
str

### Required
Yes

### Example
```py
breathe_default_project = "My Project"
```

## exhale_args (dict)

### Description
A dictionary of configuration arguments for Exhale. Users must provide values for the required keys: `containmentFolder`, `rootFileName`, and `doxygenStripFromPath`. Optional keys include `rootFileTitle`, `verboseBuild`, `alwaysColorize`, and `generateBreatheFileDirectives`.

### Type
dict

### Required
Yes

### Keys
- **containmentFolder** (str) - Required. The folder where the generated API documentation will be placed.
- **rootFileName** (str) - Required. The name of the root file for the generated API documentation.
- **doxygenStripFromPath** (str) - Required. A string to strip from the Doxygen XML paths.
- **rootFileTitle** (str) - Optional. The title for the root API document.
- **verboseBuild** (bool) - Optional. Enables verbose build logging.
- **alwaysColorize** (bool) - Optional. Enables colorized output.
- **generateBreatheFileDirectives** (bool) - Optional. Controls generation of Breathe file directives.

### Example
```py
exhale_args = {
    "containmentFolder": "./api",
    "rootFileName": "api",
    "doxygenStripFromPath": "../",
    "rootFileTitle": "My Project API",
    "verboseBuild": True,
    "alwaysColorize": True,
    "generateBreatheFileDirectives": True
}
```
```

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

### Graphviz diagram: hierarchy key-value mapping

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

Graphviz DOT diagram showing the mapping between hierarchy keys (clike, define, directory, enum, file, function, namespace, typedef, union, variable) and their value types (dict, parameters, or ????). Used to illustrate how hierarchy nodes are represented in the testing module.

```dot
digraph G {
  rankdir="LR";
  ranksep=0.88;
  edge [dir=none];

  subgraph cluster_exhale {
    style=filled;
    color="#a2ddf9";
    label="Exhale Type";
    fontsize=22;
    node [style=filled, shape=rectangle, fontname="Courier"];
    subgraph cluster_hacksize {
     label=" ";// soooo hacky...
     fontsize=18;

    fake_node_1 [style=none, shape=none, label=""];
    fake_node_2 [style=none, shape=none, label=""];
    fake_node_3 [style=none, shape=none, label=""];
    fake_node_4 [style=none, shape=none, label=""];
    exhale_node [label="exhale.graph.ExhaleNode"];
    fake_node_5 [style=none, shape=none, label=""];
    fake_node_6 [style=none, shape=none, label=""];
    fake_node_7 [style=none, shape=none, label=""];
    fake_node_8 [style=none, shape=none, label=""];
    fake_node_9 [style=none, shape=none, label=""];
    }
  }

  subgraph cluster_testing {
    style=filled;
    color="#f7f389";
    label="Testing Types";
    fontsize=22;
    node [
      style=filled,
      shape=rectangle,
      fontname="Courier",
      width=2,
      fixedsize=true
    ];

    hierarchy_node [label="hierarchies.node"];

    subgraph cluster_keys {
      style=filled;
      color=cadetblue;
      label="Key Type";
      fontsize=18;

      clike;
      define;
      directory;
      enum;
      file;
      function;
      namespace;
      typedef;
      union;
      variable;
    }

    subgraph cluster_values {
      style=filled;
      color=mediumaquamarine;
      label="Value Type";
      fontsize=18;

      v_clike     [label="dict"];
      v_define    [label="????"];
      v_directory [label="dict"];
      v_enum      [label="????"];
      v_file      [label="dict"];
      v_function  [label="parameters"];
      v_namespace [label="dict"];
      v_typedef   [label="????"];
      v_union     [label="dict"];
      v_variable  [label="????"];
    }
  }
}
```

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

### Download and rename BeautifulSoup objects.inv

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

Downloads the original objects.inv from the BeautifulSoup docs and renames it to bs4_objects.inv for local use.

```console
$ curl -O https://www.crummy.com/software/BeautifulSoup/bs4/doc/objects.inv
$ mv objects.inv bs4_objects.inv
```

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

### Macro add_open_cpp_coverage_source_dirs

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

Defines a macro to append source directories to the OPEN_CPP_COVERAGE_SOURCE_LIST variable, which is then set in the parent scope for MSVC builds.

```cmake
macro(add_open_cpp_coverage_source_dirs)
  if (MSVC)
    foreach (dir ${ARGV})
      list(APPEND OPEN_CPP_COVERAGE_SOURCE_LIST ${CMAKE_CURRENT_SOURCE_DIR}/${dir})
    endforeach()
    set(OPEN_CPP_COVERAGE_SOURCE_LIST "${OPEN_CPP_COVERAGE_SOURCE_LIST}" PARENT_SCOPE)
  endif()
endmacro()
```

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

### Enable unicode literals in Python 2

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

Add this import at the top of every file to ensure all string literals are unicode, as used throughout Exhale's codebase.

```python
from __future__ import unicode_literals
```

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

### Rendered output of the double-colon indentation method

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

The resulting Python code block as it appears when rendered by Sphinx.

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

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

### Root document structure with .. include:: directives

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

Shows the structure of the root document that Exhale generates. The includes reference files that may or may not be generated depending on the compounds documented in Doxygen and other settings. These files should not use a file extension found in sphinx:source_suffix to avoid duplicate label warnings.

```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
```

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

### Define custom macros for Doxygen

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

Define macros that Doxygen might otherwise struggle to parse, such as custom namespace wrappers.

```cpp
#define NAMESPACE_BEGIN(name) namespace name {
#define NAMESPACE_END(name) }
```

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

### Exhale Execution Flow Graphviz

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

A Graphviz diagram illustrating the execution flow of Exhale, from the initial 'make html' command through configuration application and Sphinx parsing.

```graphviz
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!"
    ];
}
```

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

### Rendered output of a code-block directive

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

The resulting C++ code block as it appears when rendered by Sphinx.

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

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

### Add Clean Target to Makefile

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

Update the Makefile to remove the generated API and Doxygen directories when running make clean. Ensure you use TAB characters for indentation.

```make
.PHONY: help Makefile clean

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

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

### Define coverage-xml target

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

Adds a custom target that runs OpenCppCoverage with cobertura export, intended for codecov.io. Invoke with cmake --build . --target coverage-xml.

```CMake
add_custom_target(
    coverage-xml
    COMMAND ${OPEN_CPP_COVERAGE_EXE} ${OPEN_CPP_COVERAGE_SOURCES}
      --working_dir "\"${PROJECT_BINARY_DIR}\""
      --export_type cobertura:coverage.xml
      -- $<TARGET_FILE:exhale-projects-unit-tests>
    WORKING_DIRECTORY ${PROJECT_BINARY_DIR}
    DEPENDS exhale-projects-unit-tests
  )
```

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

### Link Generated API in toctree

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

Add the generated API root file to your index.rst to include it in the documentation navigation.

```rst
.. toctree::
   :maxdepth: 2

   about
   <b>api/library_root</b>
```

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

### Set ipdb trace in test

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

Insert an ipdb breakpoint in a test to debug failures. ipdb is preinstalled in the test environment and works like pdb.

```py
import ipdb
ipdb.set_trace()
```

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

### Set page-level metadata for GitHub URL in Exhale

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

Use the page-level metadata feature of Exhale to set a GitHub URL for the generated pages. This makes the 'View Page Source' link point to an existing location, but note that locally the link to view the generated reStructuredText is removed, so you must open the file manually in the folder specified by containmentFolder.

```python
exhale_args = {
    # ... required / optional arguments ...
    "pageLevelConfigMeta": ":github_url: https://github.com/username/project"
}
```

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

### Apply confoverrides to test method

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

Apply configuration overrides to a single test method. Method-level overrides are combined with class-level ones and take precedence.

```py
@confoverrides(conf_var1=conv_val1, conf_var2=conf_val2)
def test_something(self):
    ...
```

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

### Graphviz diagram: ExhaleRoot represents hierarchy root

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

Graphviz DOT diagram showing that exhale.graph.ExhaleRoot represents the testing.hierarchies.root, with file_hierarchy and class_hierarchy as children. Used to illustrate the relationship between Exhale and testing types.

```dot
digraph G {
  rankdir="LR";
  ranksep=0.88;
  edge [dir=none];

  subgraph cluster_exhale {
    style=filled;
    color="#a2ddf9";
    label="Exhale Type";
    fontsize=22;
    node [style=filled, shape=rectangle, fontname="Courier"];
    e_fake_root_1 [style=none, shape=none, label=""];
    exhale_root [label="exhale.graph.ExhaleRoot"];
    e_fake_root_2 [style=none, shape=none, label=""];
  }

  subgraph cluster_testing {
    style=filled;
    color="#f7f389";
    label="Testing Types";
    fontsize=22;
    node [
      style=filled,
      shape=rectangle,
      fontname="Courier",
      width=2,
      fixedsize=true
    ];

    fake_root_1 [style=none, shape=none, label=""];
    hierarchy_root [label="hierarchies.root"];
    fake_root_2 [style=none, shape=none, label=""];
    file_hierarchy [label="file_hierarchy"];
    fake_hierarchy [style=none, shape=none, label=""];
    class_hierarchy [label="class_hierarchy"];


    hierarchy_root:e -> file_hierarchy:w;
    hierarchy_root -> fake_hierarchy [style=none, color=none];
    hierarchy_root:e -> class_hierarchy:w;

    {rank=same; fake_root_1; hierarchy_root; fake_root_2}
    {rank=same; class_hierarchy; fake_hierarchy; file_hierarchy}
  }

  exhale_root -> hierarchy_root [style=dashed, label="represents"];
}
```

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

### Write files with UTF-8 encoding

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

Use codecs.open with utf-8 encoding when writing files to ensure proper unicode support.

```python
with codecs.open(file_name, "w", "utf-8") as f:
```

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

### Run tox -e py with -s for debugging

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

Run Python unit tests with pytest's -s flag to allow the debugger to stop at breakpoints. Without -s, the test fails at the breakpoint.

```console
$ tox -e py -- -s
```
Tokens:
Raw