Hyde

Theme by Adobe

|

Updated: 1 Oct 2024

|

330 Stars

A front-end to Jekyll that parses C++ sources to produce and enforce out-of-line documentation

Overview

Hyde is a utility that facilitates documenting C++. It is unique from existing documentation utilities in several ways. First, it is based on Clang’s libTooling library, allowing it to compile and document C++ code as the language evolves. Second, it uses out-of-line documentation instead of inline comments, avoiding the problem of comments falling out of sync and becoming a distraction. Third, it produces well-structured Markdown files with YAML front-matter, making it compatible with tools like Jekyll for customizing the final documentation’s structure and layout. Fourth, Hyde enforces schema to keep the documentation in sync with the C++ code. Lastly, it is adaptable, allowing additional tools or emitters to be built on top of its output.

Features

• Clang based: Hyde uses Clang’s libTooling library to compile and document C++ code.
• Out-of-line documentation: Hyde avoids inline comments and uses separate documentation files to prevent syncing issues and distractions.
• Jekyll compatible: Hyde produces well-structured Markdown files with YAML front-matter, making it compatible with tools like Jekyll.
• Schema enforcement: Hyde compares pre-existing documentation files with the current state of the C++ sources to keep the documentation accurate.
• Adaptable: In addition to documentation, Hyde can output AST-based information about the code as a JSON-based IR, allowing for additional tools or emitters to be built on top.

Installation

Requirements

• macOS:
  • Homebrew: brew install cmake
  • Optional: brew install ninja
• Linux (Ubuntu Bionic):
  • sudo apt-get install libyaml-cpp-dev

Building Hyde

1. Clone the repository: git clone <repository-url>
2. Change into the Hyde directory: cd hyde
3. Initialize submodules: git submodule update --init
4. Create a build directory: mkdir build
5. Change into the build directory: cd build
6. Configure the build with CMake: cmake .. -GNinja (or specify your preferred generator)
7. Build Hyde with Ninja: ninja (or use your chosen build tool)

Using Docker

• You may need to increase your Docker resources to build the Hyde image.

Parameters and Flags

• Hyde can run in several modes:
  • -hyde-json (default): Output an analysis dump of the input file as JSON.
  • -hyde-validate: Validate existing YAML documentation.
  • -hyde-update: Write updated YAML documentation.
  • -hyde-src-root=<path>: The root path to the header file(s) being analyzed, affecting defined_in.

Summary

Hyde is a unique utility that facilitates documenting C++ code. By using Clang’s libTooling library, it keeps the documentation up to date with the evolving C++ language. With its out-of-line documentation approach, Hyde avoids syncing issues and distractions that can arise from inline comments. It also produces well-structured Markdown files with YAML front-matter, making it compatible with tools like Jekyll for customization. Hyde enforces schema to ensure the documentation accurately reflects the code, and it is adaptable, allowing additional tools or emitters to be built on top of its output.