IMPORTANT: This README and the documentation reflect what we want and not what is available. Please check the 2020 Summer Intership project board for the current progress.
underdocs is a modern, performant documentation generator for C. Notable features include the following:
- Only C, No C++. Is this even a feature? In our opinion, absolutely. underdocs is not another C++ documentation generator with accidental support for C. We only support C18 and do not plan to ever add support for C++.
- Inspired by CppReference. If you know CppReference, then you'll feel right at home. The documentation format and the generated sites are heavily inspired by CppReference.
- Modern, performant HTML output with support for custom styling. With optional build-time pre-rendering (needs GraalVM to be enabled), underdocs generates fast and stylish HTML output with support for customization. Pre-rendering allows us to ship minimal client-side JavaScript to keep your site as fast as possible.
- Markdown-based documentation format. underdocs comes with its own doc comment format, based on Markdown. You are free to use arbitrary Markdown formatting in your docs, including support for images, code snippets with syntax highlighting (via Prism) and mathematical expressions (via KaTeX).
- On-Site Search. A huge project may contain thousands of headers, structs, functions and such. underdocs makes it easy to navigate such projects by providing on-site search capabilities using a precomputed index.
- Multiversion Sites. If you support multiple versions of your project simultaneously, then the need naturally arises to host the documentation of each supported version. underdocs makes this a breeze with out of the box support for such scenarios.
In no particular order, we also have:
- Out of the box night mode.
- Client-side preprocessor conditional evaluation.
- Remote repository link integration (for code files and tags).
- Mobile-ready output.
- Module and file level commitlogs between versions.
- Easy-to-extend architecture.
Check out the Documentation for detailed information on these features.
For the impatient, we offer a "quicker than Quickstart guide" here.
-
Ensure some JRE.
Our only dependency is the Java Runtime Environment (version 11 or above). If you want to enjoy the complete underdocs experience with pre-rendering, then make sure to use GraalVM. An easy solution to obtain GraalVM is jabba or jdk-via-jabba if you're on GitHub Actions.
-
Initialize underdocs.
Move into your project's directory:
cd my-c-projectDownload underdocs and create a new configuration file:
wget -q https://underdocs.dev/underdocs.jar java -jar underdocs init
-
Parse and render the codebase.
Generating documentation with underdocs is a two-step process. First you parse the codebase into a JSON file, then render it to HTML.
java -jar underdocs.jar parse java -jar underdocs.jar render
-
Visit the documentation site.
Fire up an HTTP-server (for example http-party/http-server) serving the output directory (set with the
initcommand) and check out your new documentation site!
If you did not use the underdocs documentation style throughout your headers, then the generated site will look pretty boring. Make sure to check the next section, Learning underdocs on how to get the most out of underdocs!
The full documentation for underdocs lives in the docs folder. The following resources might be of most interest:
- Quickstart Guide. A few-minute introduction to the underdocs flow.
- The underdocs Format. An in-depth description of the underdocs doc comment style and its capabilities.
- Configuration Reference. Detailed description of the available configuration options.
- Example Projects. Multiple example projects showcasing different features of underdocs.
Contributions are always welcome in underdocs! Take a look at the Contributing Guide for more information (including setup and development related stuff).
Licensed under the Apache License 2.0.