Adding mdbook-based user manual
This commit is contained in:
parent
592ce859de
commit
37688e70a3
|
|
@ -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:
|
||||
|
|
@ -129,13 +122,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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
- run: |
|
||||
working-directory: book
|
||||
mv ../target/thumbv7em-none-eabihf/doc src/firmware
|
||||
mdbook build
|
||||
|
||||
- uses: peaceiris/actions-gh-pages@v3.8.0
|
||||
with:
|
||||
|
|
|
|||
|
|
@ -1,2 +1 @@
|
|||
/target
|
||||
docs/_site/
|
||||
|
|
|
|||
|
|
@ -0,0 +1,2 @@
|
|||
stabilizer-manual
|
||||
src/firmware
|
||||
|
|
@ -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`.
|
||||
|
|
@ -0,0 +1,16 @@
|
|||
[book]
|
||||
authors = ["Ryan Summers"]
|
||||
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]
|
||||
|
|
@ -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)
|
||||
|
Before Width: | Height: | Size: 60 KiB After Width: | Height: | Size: 60 KiB |
|
Before Width: | Height: | Size: 93 KiB After Width: | Height: | Size: 93 KiB |
|
Before Width: | Height: | Size: 22 KiB After Width: | Height: | Size: 22 KiB |
|
Before Width: | Height: | Size: 21 KiB After Width: | Height: | Size: 21 KiB |
|
|
@ -1,17 +1,3 @@
|
|||
---
|
||||
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 }
|
||||
|
||||
|
|
@ -54,7 +40,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.
|
||||
|
||||
|
||||
|
||||
|
||||
All of the instructions below assume you have properly [`built the firmware`](#building-firmware).
|
||||
|
||||
|
|
@ -143,7 +129,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.
|
||||
|
||||
|
||||
|
||||
|
||||
> **Note**: Use the same broker address that you defined in the firmware for MQTT explorer.
|
||||
|
||||
|
|
@ -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:/
|
|||
[](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).
|
||||
|
|
@ -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.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 6.1 KiB |
|
|
@ -1,4 +0,0 @@
|
|||
source 'https://rubygems.org'
|
||||
gem "just-the-docs"
|
||||
gem "jekyll-remote-theme"
|
||||
gem "html-proofer"
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
BIN
docs/favicon.ico
BIN
docs/favicon.ico
Binary file not shown.
|
Before Width: | Height: | Size: 1.1 KiB |
Loading…
Reference in New Issue