Software documentation for Spartan Robotics.
This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.
This project uses MkDocs with the Material theme. Both sites contain plenty of documentation information.
The docs are written in Markdown, which is very close to plain text and easy to pick up. This manual is an excellent reference source. Be aware that a few extended syntax features may not actually work with MkDocs.
It's a good idea to check the rendering of your documentation before committing it. A local setup can be done pretty easily, thankfully.
Start by installing the python requirements:
pip install -r requirements.txt
And then render an automatically-refreshing output to 127.0.0.1.8000:
mkdocs serve
It's that easy!
New pages can be added by creating a .md file somewhere in the docs directory. Follow the pattern shown at the bottom of mkdocs.yml to add them to the navigation sidebar.
Math expressions are supported, using the MathJax Javascript library. LaTeX is a complicated beast, but we only use its math expression syntax. MathJax's LaTeX documentation is a good place to start.
Mermaid is a very slick library for generating charts, using similar syntax to Markdown. Documentation on using Mermaid in MkDocs can be found here, and general Mermaid information at the official site.
Markdown doesn't support a few things that we want to do in our documentation, notably the embedded compiler and spoiler tags for code. Instead, we have to use raw HTML. Macros help with this process-- instead of manually adding all the tags ourselves, we can call a macro which applies the proper tags. The macros are processed before Markdown is turned into HTML and before HTML is rendered, so the generated text is just as real to them as anything else.
Macros are written in Python, and live inside the main.py file. That file should be formatted with black (black .).
Invoking a macro is done with {{ macroName(arg1, arg2, ...)}}. Further documentation can be found here.