https://github.com/team997coders/software-resources
Software documentation for Spartan Robotics.
https://github.com/team997coders/software-resources
Last synced: about 1 year ago
JSON representation
Software documentation for Spartan Robotics.
- Host: GitHub
- URL: https://github.com/team997coders/software-resources
- Owner: Team997Coders
- Created: 2023-09-10T21:27:39.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2023-09-10T21:28:49.000Z (over 2 years ago)
- Last Synced: 2025-01-21T22:31:00.559Z (over 1 year ago)
- Language: Python
- Homepage: https://team997coders.github.io/software-resources/
- Size: 775 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Spartan Robotics Software Resources
Software documentation for Spartan Robotics.
## [View on GitHub Pages!](https://team997coders.github.io/software-resources/)
This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.
## Contributing
This project uses [MkDocs](https://www.mkdocs.org/) with the [Material](https://squidfunk.github.io/mkdocs-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](https://www.markdownguide.org/) is an excellent reference source. Be aware that a few extended syntax features may not actually work with MkDocs.
### Working Locally
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!
### Adding New Pages
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.
### MathJax/LaTeX
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](https://docs.mathjax.org/en/latest/input/tex/index.html) is a good place to start.
### Mermaid2
Mermaid is a very slick library for generating charts, using similar syntax to Markdown. Documentation on using Mermaid in MkDocs can be found [here](https://mkdocs-mermaid2.readthedocs.io/en/latest/), and general Mermaid information at [the official site](https://mermaid.js.org/community/n00b-overview.html).
### Macros
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](https://github.com/psf/black) (`black .`).
Invoking a macro is done with `{{ macroName(arg1, arg2, ...)}}`. Further documentation can be found [here](https://mkdocs-macros-plugin.readthedocs.io/en/latest/pages/).