Cleanup documentation

[ebelski]

Document all of the progress made so far, clean up some of the descriptions in the readme, and begin laying out the wiki.

[mciantyre]

Count me in. I have some other developer docs to add. I may add the following to the README, just as a reminder for us and for any newcomers:

Generating source documentation

If you want to see the rendered in-source documentation, run

cargo doc --all --open

at the top of the repo. When the command finishes, it should open your browser with the documentation to a crate in the repo. Use the "Crates" column on the left to jump to the documentation for any other crate. Helpful crate docs include

• demo_pwm_control, which has the PWM pinout, and a depiction of how an ESC protocol is represented with a PWM signal
• teensy4_bsp, which has a sparse table describing the Teensy 4's pinout and pin functions

We put other software-related notes, tests, and examples in the source docs. When we run tests, the compiler will check the tests and examples in the documentation for correctness. So by default, we're guaranteed that code samples in documentation are buildable. You'll never copy-and-paste broken code.

[ebelski]

For sure!

What type of organization paradigm are you thinking for the source docs? Will those live as readmes in the repo?

[ebelski]

Ultimately, once we get near the end of the build (much further in the future) I'd like for us to author a detailed paper on the process and methodology we took. So I'm game for any organizational scheme that is easy to interpret and useful.

[mciantyre]

We'll want to keep detailed, module-level software docs in source code, as they are now. The cargo doc workflow is the de-facto way for sharing Rust code documentation.

For things like architectures, test plans and results, and design docs of hardware and software and controls, I see a few options:

• GitHub Wikis. Edit them in the browser. We can also treat them as another git repo, and edit the contents locally. Could be a good starting point.
• Sphinx is flexible. I don't think it'd be something we would ever outgrow. It would help us organize and cross-reference our docs.
• If the goal is a paper, could start up-front with raw LaTeX! But, Sphinx also outputs LaTeX for PDF generation.

[mciantyre]

On second thought, I might replace GitHub Wiki with “Markdown files checked into the main repo.” It’s easier for us to version and release documentation with code, data, and models if it’s all in one repo. It’s also easier to look back and see how the project evolved through one version control history.

[ebelski]

I like the idea of using markdown files stored and versioned in the main repo!

[mciantyre]

mciantyre/teensy4-rs#74 shows that we can build and publish API documentation from a GitHub repo. The process publishes the content to https://mciantyre.github.io/teensy4-rs/. We could do something similar here. We'll need to figure out how it plays with the current GitHub pages publication.