hdoc is streamlined to make it easy to use with sensible default options and configurability where you need it. The following instructions show how to get hdoc and use it on your codebase.
Once you've made an account, (optionally) subscribed, and created a project, you can download hdoc releases from the Releases page of the hdoc console. Make sure you save the API key given to you when you created the project! You'll need it later.
hdoc ships as a completely static Linux x86_64 binary, and you should always download the most recent release of hdoc. It has no runtime dependencies and runs on all recent Linux systems. Before running hdoc, you must make the binary you downloaded executable using the following command:
chmod +x path/to/hdoc-online
Now you're ready to set up your project with hdoc.
hdoc needs a configuration file to do its job.
By convention, the hdoc configuration file is named .hdoc.toml and lives in the root of your project directory (that's where your .git folder is located).
Here's the bare minimum .hdoc.toml file that you need:
[project]
name = "my-project"
version = "1.0.0"
# Optional, adding this will enable direct links from the documentation
# to your source code.
git_repo_url = "https://github.com/MYUSERNAME/MYPROJECT/"
git_default_branch = "main"
[paths]
compile_commands = "build/compile_commands.json"
The information in the example above should be adjusted to match those of your project.
More information about configuration options can be found in the Configuration File Reference.
hdoc needs a special file named compile_commands.json to work.
This file contains information that hdoc needs to analyze your code.
The compile_commands.json file is typically generated by your build system when you first set your project up on your computer.
Most major build systems are able to create a compile_commands.json with an extra flag.
Alternatively, you can use other tools to analyze your project and create a compile_commands.json file:
compile_commands.json fileOnce this file has been created you are ready to run hdoc.
You need an API key to run hdoc.
An API key was given to you when you first created your project in the console.
The HDOC_PROJECT_API_KEY environment variable must contain this API key when you run hdoc.
If you forgot your API key, you can revoke it in the console and generate a new one.
Now that you have hdoc installed and your project has an hdoc configuration file, it's time to run hdoc.
This part is easy, all you have to do is open up a terminal and enter the root directory of your project where the .hdoc.toml file is located.
Once there, run hdoc as follows:
export HDOC_PROJECT_API_KEY=the.api.key.from.the.hdoc.console
hdoc-online --verbose
The --verbose flag will instruct hdoc to print extra information.
It can be omitted for future runs.
Once hdoc has finished analyzing your project, it will securely upload your documentation for hosting at docs.hdoc.io.
The address at which your documentation is hosted can be found under Projects in the hdoc console.
The address will also be printed in the terminal at program completion if the --verbose flag was passed to hdoc.
For large projects, documentation may take several minutes to become available at the address while it's being processed.
Now that you have the basics down, you can use hdoc's features to customize and enhance your documentation.