libhal.github.io

Organization wide repo for docs, assets, and tools any other static information.

Updating the docs

libhal uses mkdocs-material for our static documentation and sphinx for our API documentation

If you'd like to contribute to the libhal website and documentation you can do so by quickly setting up the enviornement by running the following commands. Please note that the build script is designed for a bash environment and is intended to be used on unix-based operating systems. The documentation is fully compatible with Windows, however you will need to write your own .bat install script or run the commands individually (as well as switch from bash's commands to powershell or command prompt's variants of them).

Please first install python 3.10 or later. Then run the following to install the required packages for running the documentation.

pip install -r requirements.txt

Now to actually build the documentation.

./build.sh

[!NOTE] You may need to run chmod +x build.sh to run it.

Finally to serve the documentation:

mkdocs serve

The page should be available on this address http://127.0.0.1:8000.

Now whenever you update the markdown in the mkdocs directory, the page will auto-reload with your changes, however if you are making changes to the API documentation, you must rebuild the documentation. If you changed just rst or md files in the sphinx directory you can simply run the command inside the sphinx directory.

sphinx-build -b html -Dbreathe_projects.libhal=../doxygen_output/xml . output

If things changed in the actual code for the documentation, you will need to build the doxygen files as well. Run the following starting in the root of this repo.

doxygen Doxyfile.in
cd sphinx
sphinx-build -b html -Dbreathe_projects.libhal=../doxygen_output/xml . output

Checkout mkdocs-material for more details on the features that can be used for the static side of this site.

Checkout sphinx for how to use sphinx at a basic level, breathe on how to use doxygen directives on how to organize your code inside of sphinx rst or md files, and finally the theme for theme specific uses for the API documentation.

Contributing

See CONTRIBUTING.md for details.

License

Apache 2.0; see LICENSE for details.