Checking Generated Documentation
After making code or documentation changes, it is a best practice to generate the documentation so you can visualize those changes and check that your intention for the change materialized.
There are two kinds of documentation: scaladoc generated API documentation for developers working with the RIDDL source code, and the main hugo generated user documentation.
Scala 3 API documentation is generated from the source code. This is very simple to do:
> project root
> open doc/src/main/hugo/static/apidoc/index.html
That last command (on MacOS) will open the root of the API documentation in your browser. On other platforms, do something equivalent.
If you want to view the last released public version of the API documentation it will be at https://riddl.tech/apidoc
You need to make sure Hugo is installed:
brew install hugo
but you only need to do this once.
Follow the instructions above.
Then run the hugo server:
hugo server --disableFastRender -D
--disableFastRender means that hugo won’t cache results but read from
source on each request. The
-D option instructs to load all pages, even
the ones marked as drafts. The
hugo server command, if left running, will
update its output when the input (in
To view the site in your browser:
Note that if that port is busy, hugo may use another one. It will print out the URL it used so you should just be able to click on it from your terminal window.
You can continue editing while the server is running. This allows you to validate your work on the markdown files visually in the browser. Whenever you change a markdown file, Hugo will notice and reload the browser page automatically if the viewed markdown page changed.