431: Adding mdbook-based user manual r=ryan-summers a=ryan-summers

This PR fixes #428 by removing Jekyll in favor of using mdbook to generate documentation for Stabilizer.

Sample overview page:
![image](https://user-images.githubusercontent.com/8771450/128714012-bb017fda-4ff4-47dc-9d3a-b32d1ba1c663.png)

TODO:
 - Verify release CI

Co-authored-by: Ryan Summers <ryan.summers@vertigo-designs.com>
master
bors[bot] 2021-08-09 13:37:45 +00:00 committed by GitHub
commit c8acfe98ab
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
21 changed files with 96 additions and 263 deletions

View File

@ -89,25 +89,18 @@ jobs:
steps:
- uses: actions/checkout@v2
- uses: actions/setup-ruby@v1
with:
ruby-version: 2.7.x
- uses: actions-rs/toolchain@v1
with:
toolchain: stable
target: thumbv7em-none-eabihf
override: true
- uses: actions/cache@v2
with:
path: docs/vendor/bundle
key: ${{runner.os}}-gems-${{ hashFiles('**/Gemfile.lock') }}
restore-keys: |
${{ runner.os }}-gems-
- uses: Swatinem/rust-cache@v1
- uses: peaceiris/actions-mdbook@v1
with:
mdbook-version: '0.4.12'
- name: Install Deadlinks
uses: actions-rs/cargo@v1
with:
@ -115,6 +108,12 @@ jobs:
args: |
cargo-deadlinks
- name: Install Linkcheck
uses: actions-rs/cargo@v1
with:
command: install
args: mdbook-linkcheck
- name: cargo doc
uses: actions-rs/cargo@v1
with:
@ -129,13 +128,9 @@ jobs:
# auto-generated code.
args: --dir target/thumbv7em-none-eabihf/doc --ignore-fragments --check-http --check-intra-doc-links
- name: Test Site
working-directory: docs
- name: Test Book
working-directory: book
run: |
# Install depedencies at our cache location
bundle config path vendor/bundle
bundle install
bundle exec rake build
mv ../target/thumbv7em-none-eabihf/doc _site/stabilizer/firmware
bundle exec rake test
mv ../target/thumbv7em-none-eabihf/doc src/firmware
mdbook build

View File

@ -20,12 +20,28 @@ jobs:
target: thumbv7em-none-eabihf
override: true
- uses: Swatinem/rust-cache@v1
- name: Install Linkcheck
uses: actions-rs/cargo@v1
with:
command: install
args: mdbook-linkcheck
- uses: peaceiris/actions-mdbook@v1
with:
mdbook-version: '0.4.12'
- uses: actions-rs/cargo@v1
with:
command: doc
args: --no-deps -p miniconf -p ad9959 -p stabilizer -p dsp
- run: mv target/thumbv7em-none-eabihf/doc docs/firmware
- name: Build Book
working-directory: book
run:
mv ../target/thumbv7em-none-eabihf/doc src/firmware
mdbook build
- uses: peaceiris/actions-gh-pages@v3.8.0
with:

1
.gitignore vendored
View File

@ -1,2 +1 @@
/target
docs/_site/

2
book/.gitignore vendored Normal file
View File

@ -0,0 +1,2 @@
/stabilizer-manual/
/src/firmware/

21
book/README.md Normal file
View File

@ -0,0 +1,21 @@
# Stabilzer User Manual
This folder hosts the source used for generating Stabilizer's user manual.
The user manual is generated using `mdbook`, which can be installed via cargo:
```
cargo install mdbook
cargo install mdbook-linkcheck
```
To build the user manual locally, build docs for the firmware, copy them into the book source
directory, and then sere the book:
```
cargo doc --no-deps -p miniconf -p stabilizer -p dsp -p ad9959
mv target/thumbv7em-none-eabihf/doc book/src/firmware
cd book
mdbook serve
```
Once the `mdbook serve` command is run, the manual can be found on a web browser at
`localhost:3000`.

16
book/book.toml Normal file
View File

@ -0,0 +1,16 @@
[book]
authors = ["Ryan Summers", "Robert Jördens"]
language = "en"
multilingual = false
src = "src"
title = "Stabilizer"
[build]
create-missing = false
build-dir = "stabilizer-manual"
[output.html]
site-url = "https://quartiq.de/stabilizer"
git-repository-url = "https://github.com/quartiq/stabilizer"
[output.linkcheck]

7
book/src/SUMMARY.md Normal file
View File

@ -0,0 +1,7 @@
# Summary
- [Overview](./overview.md)
- [Getting Started](./getting-started.md)
- [Usage](./usage.md)
- [Application: Dual-IIR](./firmware/dual_iir/index.html)
- [Application: Lockin](./firmware/lockin/index.html)

View File

Before

Width:  |  Height:  |  Size: 60 KiB

After

Width:  |  Height:  |  Size: 60 KiB

View File

Before

Width:  |  Height:  |  Size: 93 KiB

After

Width:  |  Height:  |  Size: 93 KiB

View File

Before

Width:  |  Height:  |  Size: 22 KiB

After

Width:  |  Height:  |  Size: 22 KiB

View File

Before

Width:  |  Height:  |  Size: 21 KiB

After

Width:  |  Height:  |  Size: 21 KiB

View File

@ -1,19 +1,4 @@
---
title: Getting Started
layout: default
permalink: /getting-started
nav_order: 2
---
## Table of Contents
{: .no_toc .text-delta }
1. TOC
{:toc}
---
# Getting Started
{: .no_toc }
There are a number of steps that must be completed when first getting started with Stabilizer.
1. Update the Stabilizer Application
@ -54,7 +39,7 @@ Firmware is loaded onto stabilizer utilizing an ST-Link (V2-1 or greater) JTAG p
Ensure the ST-Link is connected to Stabilizer as shown below.
![JTAG Connection]({{site.baseurl}}/assets/stabilizer-jtag.jpg)
![JTAG Connection](assets/stabilizer-jtag.jpg)
All of the instructions below assume you have properly [`built the firmware`](#building-firmware).
@ -143,7 +128,7 @@ dt/sinara/dual-iir/00-11-22-33-44-55/telemetry
Download [MQTT-Explorer](http://mqtt-explorer.com/) to observe which topics have been posted to the
Broker.
![MQTT Explorer Configuration]({{site.baseurl}}/assets/mqtt-explorer.png)
![MQTT Explorer Configuration](assets/mqtt-explorer.png)
> **Note**: Use the same broker address that you defined in the firmware for MQTT explorer.

View File

@ -1,20 +1,4 @@
---
title: Home
layout: default
nav_order: 1
permalink: /
---
# Stabilizer
{: .no_toc }
## Table of Contents
{: .no_toc .text-delta }
1. TOC
{:toc}
## Overview
# Overview
Stabilizer is a flexible tool designed for quantum physics experiments. Fundamentally, Stabilizer
samples up two two analog input signals, performs digital signal processing internally, and then
@ -27,7 +11,7 @@ implementation of digital lockin schemes.
This documentation is intended to bring a user up to speed on using Stabilizer and the firmware
provided by QUARTIQ and contributors.
## Hardware
# Hardware
The Stabilizer hardware is managed via a [separate repository](https://github.com/sinara-hw/Stabilizer).
Some information about the hardware is gathered in the [Stabilizer wiki](https://github.com/sinara-hw/Stabilizer/wiki). More detailed data, measurements, discussions, and tests have been posted in the [Stabilizer issue tracker](https://github.com/sinara-hw/Stabilizer/issues?q=is%3Aissue).
@ -35,10 +19,10 @@ Some information about the hardware is gathered in the [Stabilizer wiki](https:/
[![Hardware](https://github.com/sinara-hw/Stabilizer/wiki/Stabilizer_v1.0_top_small.jpg)](https://github.com/sinara-hw/Stabilizer)
Stabilizer can be extended and coupled with a mezzanine board. One such mezzanine is the DDS upconversion/downconversion frontend Pounder. The Pounder hardware is managed via a [separate repository](https://github.com/sinara-hw/Pounder), again with [wiki](https://github.com/sinara-hw/Pounder/wiki) and [issue tracker](https://github.com/sinara-hw/Pounder/issues?q=is%3Aissue).
## Applications
# Applications
This firmware offers a library of hardware and software functionality targeting the use of the Stabilizer hardware in various digital signal processing applications commonly occurring in Quantum Technology.
It provides abstractions over the fast analog inputs and outputs, time stamping, Pounder DDS interfaces and a collection of tailored and optimized digital signal processing algorithms (IIR, FIR, Lockin, PLL, reciprocal PLL, Unwrapper, Lowpass, Cosine-Sine, Atan2) in the [DSP crate]({{site.baseurl}}/firmware/dsp/index.html).
It provides abstractions over the fast analog inputs and outputs, time stamping, Pounder DDS interfaces and a collection of tailored and optimized digital signal processing algorithms (IIR, FIR, Lockin, PLL, reciprocal PLL, Unwrapper, Lowpass, Cosine-Sine, Atan2) in the [DSP crate](firmware/dsp/index.html).
An application, which is the compiled firmware running on the device, can compose and configure these hardware and software components to implement different use cases.
Several applications are provided by default.
@ -47,11 +31,11 @@ information.
| Application | Description |
| :---: | :---- |
| [`dual-iir`]({{site.baseurl}}/firmware/dual_iir/index.html) | Two channel biquad IIR filter |
| [`lockin`]({{site.baseurl}}/firmware/lockin/index.html) | Lockin amplifier support various various reference sources |
| [`dual-iir`](firmware/dual_iir/index.html) | Two channel biquad IIR filter |
| [`lockin`](firmware/lockin/index.html) | Lockin amplifier support various various reference sources |
### Library Documentation
## Library Documentation
The Stabilizer library docs contain documentation for common components used in all Stabilizer
applications.
The Stabilizer library documentation is available [here]({{site.baseurl}}/firmware/stabilizer/index.html).
The Stabilizer library documentation is available [here](firmware/stabilizer/index.html).

View File

@ -1,17 +1,4 @@
---
title: Usage
layout: default
nav_order: 4
permalink: /usage
---
## Table of Contents
{: .no_toc .text-delta }
1. TOC
{:toc}
## Miniconf Run-time Settings
# Miniconf Run-time Settings
Stabilizer supports run-time settings configuration using MQTT.
Settings can be stored in the MQTT broker so that they are automatically applied whenever
@ -25,7 +12,7 @@ to another. Disambiguation of devices is done by using Stabilizer's MAC address.
Settings are specific to an application. If two identical settings exist for two different
applications, each application maintains its own independent value.
### Installation
## Installation
Install the Miniconf configuration utilities:
```
python -m pip install git+https://github.com/quartiq/miniconf#subdirectory=miniconf-py
@ -39,7 +26,7 @@ python -m miniconf --help
Miniconf also exposes a programmatic Python API, so it's possible to write automation scripting of
Stabilizer as well.
### Usage
## Usage
The Miniconf Python utility utilizes a unique "device prefix". The device prefix is always of the
form `dt/sinara/<app>/<mac-address>`, where `<app>` is the name of the application and
`<mac-address>` is the MAC address of the device, formatted with delimiting dashes.
@ -61,17 +48,17 @@ Where `10.34.16.10` is the MQTT broker address that matches the one configured i
The prefix can be found for a specific device by looking at the topic on which telemetry that is
being published.
Refer to the [application documentation]({{site.baseurl}}/#applications) for the exact settings and values exposed
Refer to the [application documentation](overview.md#applications) for the exact settings and values exposed
for each application.
The rules for constructing `path` values are documented in [`miniconf`'s
documentation](https://github.com/quartiq/miniconf#settings-paths)
Refer to the documentation for [Miniconf]({{site.baseurl}}/firmware/miniconf/enum.Error.html) for a
Refer to the documentation for [Miniconf](firmware/miniconf/enum.Error.html) for a
description of the possible error codes that Miniconf may return if the settings update was
unsuccessful.
## Telemetry
# Telemetry
Stabilizer applications publish telemetry utilizes MQTT for managing run-time settings configurations as well as live telemetry
reporting.
@ -90,9 +77,9 @@ buffering requirements.
In its most basic form, telemetry publishes the latest ADC input voltages, DAC output voltages, and
digital input states.
Refer to the respective [application documentation]({{site.baseurl}}/#applications) for more information on telemetry.
Refer to the respective [application documentation](overview.md#applications) for more information on telemetry.
## Livestream
# Livestream
Stabilizer supports livestream capabilities for streaming real-time data over UDP. The livestream is
intended to be a high-bandwidth mechanism to transfer large amounts of data from Stabilizer to a
@ -101,4 +88,4 @@ host computer for further analysis.
Livestreamed data is sent with "best effort" - it's possible that data may be lost either due to
network congestion or by Stabilizer.
Refer to the the respective [application documentation]({{site.baseurl}}/#applications) for more information.
Refer to the the respective [application documentation](overview.md#applications) for more information.

BIN
book/theme/favicon.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 6.1 KiB

View File

@ -1,4 +0,0 @@
source 'https://rubygems.org'
gem "just-the-docs"
gem "jekyll-remote-theme"
gem "html-proofer"

View File

@ -1,102 +0,0 @@
GEM
remote: https://rubygems.org/
specs:
addressable (2.8.0)
public_suffix (>= 2.0.2, < 5.0)
colorator (1.1.0)
concurrent-ruby (1.1.9)
em-websocket (0.5.2)
eventmachine (>= 0.12.9)
http_parser.rb (~> 0.6.0)
ethon (0.14.0)
ffi (>= 1.15.0)
eventmachine (1.2.7-x64-mingw32)
ffi (1.15.3-x64-mingw32)
forwardable-extended (2.6.0)
html-proofer (3.19.2)
addressable (~> 2.3)
mercenary (~> 0.3)
nokogumbo (~> 2.0)
parallel (~> 1.3)
rainbow (~> 3.0)
typhoeus (~> 1.3)
yell (~> 2.0)
http_parser.rb (0.6.0)
i18n (1.8.10)
concurrent-ruby (~> 1.0)
jekyll (4.2.0)
addressable (~> 2.4)
colorator (~> 1.0)
em-websocket (~> 0.5)
i18n (~> 1.0)
jekyll-sass-converter (~> 2.0)
jekyll-watch (~> 2.0)
kramdown (~> 2.3)
kramdown-parser-gfm (~> 1.0)
liquid (~> 4.0)
mercenary (~> 0.4.0)
pathutil (~> 0.9)
rouge (~> 3.0)
safe_yaml (~> 1.0)
terminal-table (~> 2.0)
jekyll-remote-theme (0.4.3)
addressable (~> 2.0)
jekyll (>= 3.5, < 5.0)
jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0)
rubyzip (>= 1.3.0, < 3.0)
jekyll-sass-converter (2.1.0)
sassc (> 2.0.1, < 3.0)
jekyll-seo-tag (2.7.1)
jekyll (>= 3.8, < 5.0)
jekyll-watch (2.2.1)
listen (~> 3.0)
just-the-docs (0.3.3)
jekyll (>= 3.8.5)
jekyll-seo-tag (~> 2.0)
rake (>= 12.3.1, < 13.1.0)
kramdown (2.3.1)
rexml
kramdown-parser-gfm (1.1.0)
kramdown (~> 2.0)
liquid (4.0.3)
listen (3.5.1)
rb-fsevent (~> 0.10, >= 0.10.3)
rb-inotify (~> 0.9, >= 0.9.10)
mercenary (0.4.0)
nokogiri (1.11.7-x64-mingw32)
racc (~> 1.4)
nokogumbo (2.0.5)
nokogiri (~> 1.8, >= 1.8.4)
parallel (1.20.1)
pathutil (0.16.2)
forwardable-extended (~> 2.6)
public_suffix (4.0.6)
racc (1.5.2)
rainbow (3.0.0)
rake (13.0.6)
rb-fsevent (0.11.0)
rb-inotify (0.10.1)
ffi (~> 1.0)
rexml (3.2.5)
rouge (3.26.0)
rubyzip (2.3.2)
safe_yaml (1.0.5)
sassc (2.4.0-x64-mingw32)
ffi (~> 1.9)
terminal-table (2.0.0)
unicode-display_width (~> 1.1, >= 1.1.1)
typhoeus (1.4.0)
ethon (>= 0.9.0)
unicode-display_width (1.7.0)
yell (2.2.2)
PLATFORMS
x64-mingw32
DEPENDENCIES
html-proofer
jekyll-remote-theme
just-the-docs
BUNDLED WITH
2.2.22

View File

@ -1,20 +0,0 @@
This folder represents the Github Pages site that is used to host Stabilizer's user guide.
The site is hosted with Jekyll and utilizes the "Just the Docs" theme.
To run locally:
1. Install Ruby
1. Install [Jekyll](https://jekyllrb.com/)
1. Install [Bundler](https://bundler.io/)
1. From this directory:
```
bundle install
bundle exec jekyll serve
```
1. Navigate to `localhost:4000/stabilizer/` in a web browser
Note: Some of the links in the docs rely on Cargo's documentation. To make all links work locally, run:
```
cargo doc --no-deps -p dsp -p miniconf -p stabilizer -p ad9959
cp -r target/thumbv7em-none-eabihf/doc docs/firmware
```

View File

@ -1,35 +0,0 @@
# Rakefile taken from:
# https://seankilleen.com/2019/09/how-to-check-your-jekyll-based-blog-for-dead-links/
# Ensures we have the html-proofer library available to use
require 'html-proofer'
# The function that will run the proofer, so that we can re-use it between our two rake tasks
def run_htmlproofer()
options = {
# Assumes html file extensions
assume_extension: true,
file_ignore: [ /stabilizer\/firmware\/.*/ ],
url_ignore: [ /quartiq.de\/stabilizer/ ],
# The options for the curl library that's used.
:typhoeus => {
# This will stop you from getting errors when certs can't be parsed, which doesn't matter in this case.
:ssl_verifypeer => false
},
# Won't fail for local links
allow_hash_href: true,
}
# Calls html-proofer and uses the Jekyll _site folder
HTMLProofer.check_directory("./_site", options).run
end
task :test do
run_htmlproofer()
end
task :build do
sh "bundle exec jekyll build -d _site/stabilizer"
end

View File

@ -1,18 +0,0 @@
remote_theme: pmarsceill/just-the-docs
title: Stabilizer
description: "User Manual"
logo: "/assets/stabilizer-logo.png"
url: "https://quartiq.de"
baseurl: "/stabilizer"
exclude: ['README.md']
plugins:
- jekyll-remote-theme
# Enable an auxilary link in top right with a new tab open
aux_links:
"Stabilizer on Github":
- "//github.com/quartiq/stabilizer"
aux_links_new_tab: true

Binary file not shown.

Before

Width:  |  Height:  |  Size: 1.1 KiB