Numahop technical documentation.

This documentation is using mdbook and schemaspy.

Note: This documentation is very incomplete and in its early stages.

Dependencies

For building

• mdbook v0.5.2

If you dont want to install these the makefile has a setup rule Downloading the needed executables from the github release pages. Use at your own risk.

For updating the generated part of the documentation.

For updating the database explorer:

• A running NumaHOP instance.
• mariadb-j-connector jarfile
• OpenJdk17
• schemaspy jarfile
• curl

For updating the graphs:

• node24

For updating the api section:

• python3 with the tree_sitter, and tree_sitter_language_pack libraries.
• A check-out of the nuamahop source.

For running the scripts:

• bash

Generated documentation.

Some part of the documentation is generated and needs a runnning Numahop Instance and/or a clone of the source code to the version for which you want to generate the documentation. In the scripts folder there are the scripts used to update the generated part of the documentation. In the gen folder there are the cached generated documentation pieces allowing to build for the latest NumaHOP release.

The build process is as folows:

• Build the source tree of the book from the markdown in src and the generated markdown files in the include directory.
• Builds the mdbook book.
• Patch in the generated html files in the build directory.

Building and consulting offline.

The setup rule of the makefile fetches the correct mdbook version, mdbook preprocessors, and the schemaspy needed jars. But everything is compiled if you don't trust fetching the compiled versions from the web you can fetch them yourself. And place them in the vendor folder.

make vendor # Only if you want to use the provided mdbook
make build
make open

To watch changes and rebuild the book on changes. Note It can be a bit broken for autogenerated parts of the book. (See #2573)

mdbook serve 

An alternative is to use the watchexec binary to watch the src directories and livereload to server the manuals directory.

# Watch the source directories
watchexec -w developper_manual/src -w user_manual/src -- make build

# In another terminal serve the build books. 
livereload --host localhost -p 8080 -t . -d manuals -w 0.5