An online copy of the COSI book is currently hosted at https://book.cosi.clarkson.edu.
Invest in documentation and prefer simple solutions that are maintainable and transferable to others.
This repo is intended to be our new documentation solution for the labs. It's easy to serve, it's convenient to keep an offline copy, and pages are backed with markdown.
The COSI book is built with mdbook. Skim over the User Guide to get a gist for how the tool works. Particularly the explanation on SUMMARY.md.
- Install the rust programming language.
- After setting up rust run
cargo install mdbook --vers "^0.4"to get the tool. - Optionally, install some dependencies:
cargo install mdbook-graphvizwill install the Graphviz processor for writing diagrams in text (requires Graphviz on your system)
- Clone this repo
- Within the repo run
mdbook serveto preview your changes - Document!
It's highly recommended that you preview your changes before submitting them. It is very easy to make formatting mistakes, mdbook may not exactly match other markdown processors.
In CI we use the typos tool to check for typos. Recommended!
As long as the change isn't "trivial" you should always create a pull request. There is no requirement to fork the project, using a branch is preferred. If you aren't yet a part of our gitlab you should reach out to a Lab Director for an invite.
Until we get a good webhook solution all updates to this repo must be manually deployed on tiamat. Tiamat has it's own docker-compose.yaml file that is not tracked here that pulls from the latest CI build.
As root on tiamat run:
cd /docker/book
docker compose up --pull
This will pull the latest CI build and deploy it on tiamat. GitLab will only build a new image for commits/MRs to main, and may take some time to build, so ensure you see the green check before pulling.