Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/adobe/hyde

A front-end to Jekyll that parses C++ sources to produce and enforce out-of-line documentation
https://github.com/adobe/hyde

cplusplus documentation-tool jekyll libtooling

Last synced: about 1 month ago
JSON representation

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

Awesome Lists containing this project

README 

        
# What is `hyde`



`hyde` is a utility that facilitates documenting C++. The tool is unique from existing documentation utilities in the following ways:



- **Clang based**: In order to properly document your C++, `hyde` compiles it using Clang's excellent [libTooling](https://clang.llvm.org/docs/LibTooling.html) library. Therefore, as the C++ language evolves, so too will `hyde`.

- **Out-of-line**: Many tools rely on documentation placed inline within source as long-form comments. While these seem appealing at first blush, they suffer from two big drawbacks. First, there is nothing keeping the comments from falling out of sync from the elements they document. Secondly (and ironically), experienced users of these libraries eventually find inline documentation to be more of a distraction than a help, cluttering code with comments they no longer read.

- **Jekyll compatible**: `hyde` does not produce pretty-printed output. Rather, it produces well structured Markdown files that contain YAML front-matter. These files can then be consumed by other tools (like Jekyll) to customize the structure and layout of the final documentation.

- **Schema enforcement**: Because of the highly structured nature of the output, `hyde` is able to compare pre-existing documentation files against the current state of your C++ sources. Library developers can use `hyde`'s _update_ mode to facilitate updating documentation against the state of sources. Build engineers can use `hyde`'s _validate_ mode to make sure changes to a code base are accurately reflected in the latest documentation. In the end, the documentation stays true to the code with minimal effort.

- **Adaptable**: While `hyde`'s primary purpose at this point is to output and enforce documentation, the tool can also be used to output AST-based information about your code as a JSON-based IR. This makes room for additional tools to be build atop what `hyde` is able to produce, or additional emitters can be added natively to the tool.



# Example Output



`hyde` produces intermediate documentation files that the developer then fills in with additional details as necessary. The files are then fed through a static site generation tool (like Jekyll) to produce [output like this](https://stlab.cc/includes/stlab/copy_on_write.hpp/copy_on_write3CT3E/).



# Requirements



## macOS



- Homebrew

    - `brew install cmake`

    - `brew install ninja` (optional)



## Linux



(Note: only tested on ubuntu bionic so far)



- Apt

    - `sudo apt-get install libyaml-cpp-dev`



# How to Build



- clone this repo

- `cd hyde`

- `git submodule update --init`

- `mkdir build`

- `cd build`

- `cmake .. -GNinja` (or `-GXcode`, etc.)

- `ninja` (or whatever your IDE does)



LLVM/Clang are declared as a dependency in the project's `CMakeLists.txt` file, and will be downloaded and made available to the project automatically.



# How to run from Docker



```sh

docker pull ghcr.io/adobe/hyde:latest



docker run --platform linux/x86_64 --mount type=bind,source="$(pwd)",target=/mnt/host \

    --tty --interactive \

    ghcr.io/adobe/hyde:latest bash

```



You can then run the examples as below, except don't prefix `hyde` with `./`.



# Building the Docker image



You may need to increase your docker resources to build the image. (2.0.1 successfully built with 16GB RAM and 4GB swap)



```sh

docker build --tag hyde .



docker run --platform linux/x86_64 --mount type=bind,source="$(pwd)",target=/mnt/host \

    --tty --interactive \

    hyde bash

```



# Publishing the docker image (requires write access to the `adobe` GitHub organization)



Instructions for publishing a GitHub package can be found [here](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry).

Instructions for associating the with the `adobe/hyde` repository can be found [here](https://docs.github.com/en/packages/learn-github-packages/connecting-a-repository-to-a-package#connecting-a-repository-to-a-container-image-using-the-command-line).



```sh

VERSION=2.0.1

docker tag hyde ghcr.io/adobe/hyde:$VERSION

docker tag hyde ghcr.io/adobe/hyde:latest

docker push ghcr.io/adobe/hyde:$VERSION

docker push ghcr.io/adobe/hyde:latest

```



# Parameters and Flags



There are several modes under which the tool can run:



- `-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 = ` - The root path to the header file(s) being analyzed. Affects `defined_in_file` output values by taking out the root path.

- `-hyde-yaml-dir = ` - Root directory for YAML validation / update. Required for either hyde-validate or hyde-update modes.



- `--use-system-clang` - Autodetect and use necessary resource directories and include paths



- `--fixup-hyde-subfield` - As of Hyde v0.1.5, all hyde fields are under a top-level `hyde` subfield in YAML output. This flag will update older hyde documentation that does not have this subfield by creating it, then moving all top-level fields except `title` and `layout` under it. This flag is intended to be used only once during the migration of older documentation from the non-subfield structure to the subfield structure.



This tool parses the passed header using Clang. To pass arguments to the compiler (e.g., include directories), append them after the `--` token on the command line. For example:



    hyde input_file.hpp -hyde-json -use-system-clang -- -x c++ -I/path/to/includes



Alternatively, if you have a compilation database and would like to pass that instead of command-line compiler arguments, you can pass that with `-p`.



While compiling the source file, the non-function macro `ADOBE_TOOL_HYDE` is defined to the value `1`. This can be useful to explicitly omit code from the documentation.



# Examples:



To output JSON:

```./hyde -use-system-clang ../test_files/classes.cpp --```



To validate pre-existing YAML:

```./hyde -use-system-clang -hyde-yaml-dir=/path/to/output -hyde-validate ../test_files/classes.cpp```



To output updated YAML:

```./hyde -use-system-clang -hyde-yaml-dir=/path/to/output -hyde-update ../test_files/classes.cpp```



# Hyde 1 to Hyde 2 Format Conversion



As of the Hyde 2 work, all subfields in the YAML output (except the Jekyll-required `layout` and `title` fields) must go under a top-level `hyde` subfield. This allows for other tools to include additional (possibly same-named) fields under their own top-level subfields in the YAML.



Here is an example of updating from Hyde 1 to Hyde 2 formatted docs by scanning a directory for markdown-formatted files and passing them to `hyde` with the new `-hyde-fixup-subfield` mode:



    find . -name '*.md' | xargs -I % -L 1 /path/to/hyde -hyde-fixup-subfield % --



# Sass Updates



Sometimes it may be necessary to clean up or "lint" the sass files. You can do so with:



    bundle exec sass-convert -i /path/to/file.scss