Adding Stabilizer User Manual

[ryan-summers]

This PR adds a user manual to Stabilizer using Jekyll + Github Pages.

You can see a sample of this site on http://quartiq.de/stabilizer

The page is served from the pages branch and a workflow has been set up to automatically copy and release docs on that branch when master is updated.

Existing docs include:

• Flashing, building, debugging firmware
• Setting up MQTT
• Information on livestreaming
• Documentation of run-time settings.

This is intended as an initial stroke. With the framework in place, we can now easily add further docs via markdown and have them easily served to the website.

• addresses part of Documentation, Manual, CLI #339

[jordens]

A few items:

• Why can't we just use cargo doc?
• I can't seem to access the docs generated by cargo doc. Where do they appear and where are they linked?
• the readme should be reduced significantly and point to the docs.

[ryan-summers]

A few items:

• Why can't we just use cargo doc?

I originally investigated putting all of the docs into stabilizer/src/lib.rs and using cargo doc. While it does work, I wasn't really happy with the granularity it provided - it felt like there were a lot of docs jammed on one page and it didn't feel clean to me. That's not to say it's impossible, and going towards cargo-doc only is an approach that we can definitely still take if we'd like. I went with the above approach largely because I felt it was nice and clean to separate some of the docs into separate pages to make it easier to navigate and digest.

There are definite downsides to this though, such as the docs living in separate files from the source code. This risks the docs becoming outdated when source code is updated. That being said, there's also a fair number of docs that are totally unrelated to code, such as setting up MQTT, toolchains, flashing, debugging, etc.

This is why I originally went with the combined approach of cargo-doc + Github pages / Jekyll. Definitely open to feedback - it's easy to move things around and reorganize.

• I can't seem to access the docs generated by cargo doc. Where do they appear and where are they linked?

This is an oversight on my part. The docs are uploaded to firmware/<app>/index.html from the website (under http://quartiq.de/stabilizer/pages/networking/mqtt.html#settings-configuration). They're only linked from MQTT -> settings -> app specific settings, but I personally think we should add them as a direct link to the menu on the left for ease of access.

• the readme should be reduced significantly and point to the docs.

Agreed - just haven't gotten to this yet.

[jordens]

Maybe use dummy mods to structure instead of putting it all into the lib doc?
Also with 1.54 we can use external docs as below. I'm fine with requiring beta/nightly to build the docs for now. It would be nice to avoid the additional web site tooling, style and infra if we already have cargo doc. That also helps with consistency and dangling link avoidance.

#[doc = include_str!("my_doc.md")]
 struct S;

[jordens]

Also https://

[ryan-summers]

This diagram is outdated and inaccurate. Docs in this README should now point to the stabilizer user manual site.

[jordens]

@SingularitySurfer could you spin a new diagram (sample rate 781 kHz) ? The existing one's source is the SVG in the repo if you need it. I used draw.io back then.

Regarding including/showing images in cargo docs, it works just fine with relative links for all "local" crates (which is what we care about here) and with absolute links for everything else.

https://docs.rs/ndarray/0.11.2/ndarray/type.ArrayView.html#method.split_at
or
https://users.rust-lang.org/t/include-images-in-rustdoc-output/3487/4

[ryan-summers]

@jordens It looks like we can't generate docs for dsp because one of the dev-dependencies uses std. I opened an issue for it in rust-lang/cargo#9690. It looks like one of our tests is using functions from ndarray that require std (dsp/src/rpll.rs:177 and 179)

[jordens]

Ah. The pages branch should only ever contain the single HEAD commit, no history. Otherwise this will blow up. There is some git option for that IIRC.

[ryan-summers]

@jordens I've gotten htmlproofer running via rake test in the docs folder to check for correct linkage in the website

[jordens]

A couple minor things. Let's land and then tweak the rest later.

[jordens]

Let's roll.