This is a fork of hdoc, with additional functionality (and without online functionality).
It is designed specifically to add the features required to generate documentation for Celerity.
We are happy to integrate useful PRs, but we don't currently have the bandwidth to accomodate feature requests.
- Support documenting explicit template specializations of records
- Support markdown syntax in doc comments
- Document aliases (i.e. usings), both at top level namespaces and in records
- Correctly resolve file locations for symbols defined in macros (and therefore include them in the docs)
- Allow defining symbols as part of a "detail" set based on a list of namespace (sub-)strings; this set can be styled differently
- Allow ignoring symbols on namespace basis (in addition to file path)
- Include operators in documentation and format them properly
- Various improvements to presentation, especially in the presence of complex member function signatures
- Builds with Clang/LLVM 17
- Everything related to the hosting/online functionality of hdoc is unmaintained
- JSON serialization of the symbol database is unsupported
- Search (we use a search system provided by algolia)
Usage documentation is hosted at hdoc.io/docs.
The contents of this repository are a subset of a private repository where hdoc's development takes place.
- Autogenerated API documentation. hdoc generated API documentation for every function, record, enum, and namespace in your codebase.
- Integrated Markdown pages. hdoc converts your Markdown pages into a website and puts it next to your API docs. All of your documentation is in one place.
- Instant codebase search. Instant search-as-you-type lookup of symbols throughout your entire codebase.
- Easy CI integration. Your documentation is never out of date if you build it with your code. All you need to do is add hdoc to your build job.
- Advanced C++ parser. hdoc understands the newest C++ features with its advanced LLVM/Clang-based parser.
- Clean, fast output. hdoc outputs fully static HTML with no required Javascript, ensuring your users never have to wait.
hdoc depends on LLVM/Clang and OpenSSL, and all other dependencies are vendored in subprojects/
.
hdoc also comes with a Nix Flake which sets up a development environment for you with all of the needed dependencies, and should work on all Linux distributions.
Follow the instructions below to build hdoc.
# Build hdoc
meson build # Configure the build directory
ninja -C build # Compile hdoc binaries and tests
./build/hdoc --verbose # Run hdoc over itself, saving the HTML documentation to ./hdoc-output/
More instructions for using hdoc can be found at hdoc.io/docs.
Windows support for hdoc is unofficial and was contributed by @yqs112358. Windows is unofficially supported as the hdoc team does not use it for development. hdoc is not tested on Windows and no guarantee is made for its functionality there. However, the following instructions for compiling hdoc on Windows.
MSYS2
and MinGW-w64-x86_64-gcc
must be installed in order to compile hdoc on Windows.
Once the prerequisites have been installed, follow the instructions below to build hdoc:
# Install dependent packages for MinGW
pacman -S groff
pacman -S unzip
pacman -S mingw-w64-x86_64-meson
pacman -S mingw-w64-x86_64-cmake
pacman -S mingw-w64-x86_64-clang
pacman -S mingw-w64-x86_64-clang-analyzer
pacman -S mingw-w64-x86_64-clang-tools-extra
# Set PATH
export PATH=/mingw64/bin:/mingw64/lib:$PATH # You can also add this line into ~/.bashrc
# Build hdoc
meson build # Configure the build directory
ninja -C build # Compile hdoc binaries and tests
./build/hdoc --verbose # Run hdoc over itself, saving the HTML documentation to ./hdoc-output/
Reportedly, hdoc-online.exe
does not currently work on Windows due to a linking problem.
However, hdoc.exe
should work.
hdoc has a suite of unit and integration tests, which can be run using the instructions below.
# Assumes you've already built hdoc
cd build
# Running indexing tests, unit tests, and JSON serialization/deserialization tests
./hdoc-tests
# Running integration tests
cd ../tests/integration_tests
./clone-corpus-repos.sh # Pull testing repos from GitHub
./test.sh # Run hdoc over testing repos
hdoc
โโโ assets # Static HTML/CSS/Favicons used in the generated HTML docs
โโโ schemas # JSON schema for hdoc's JSON payload output
โโโ site # Source code for hdoc.io and hdoc's documentation
โโโ src # C++ source code
โย ย โโโ frontend # Parses configuration file and CLI arguments
โย ย โโโ indexer # Parses a codebase and extracts documentation from it into an index
โย ย โโโ serde # Serialization/Deserialization of hdoc's index into HTML and other formats
โย ย โโโ support # Ancillary code used to parallelize indexing
โย ย โโโ types # Types used by hdoc
โโโ subprojects # Vendored dependencies
โโโ tests # Testing code
ย ย โโโ index-tests # Unit tests of hdoc's indexing functionality
ย ย โโโ integration-tests # Integration testing scripts
ย ย โโโ json-tests # Tests for JSON serialization and deserialization
ย ย โโโ unit-tests # Unit tests for a small portion of hdoc's codebase
hdoc relies on several open source software projects. We thank all of the contributors to these projects for their work. These are listed below in alphabetical order:
- argparse
- Bulma
- Clang
- cmark-gfm
- cpp-httplib
- CTML
- doctest
- highlight.js
- KaTeX
- LLVM
- minisearch
- rapidjson
- spdlog
- toml++
More information, including licenses, can be found at hdoc.io/oss.
hdoc is available under the AGPLv3 license, or a custom commercial license. For more information about commercial licensing, reach out to [email protected].