Merge #431

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>

.github/workflows/ci.yml

@@ -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
+      - name: Test Book
-        working-directory: docs
+        working-directory: book
         run: |
           # Install depedencies at our cache location
-          bundle config path vendor/bundle
+          mv ../target/thumbv7em-none-eabihf/doc src/firmware
-          bundle install
+          mdbook build
-
-          bundle exec rake build
-          mv ../target/thumbv7em-none-eabihf/doc _site/stabilizer/firmware
-          bundle exec rake test

.github/workflows/release-docs.yml

@@ -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:

.gitignore

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

book/.gitignore

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

book/README.md

@@ -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`.

book/book.toml

@@ -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]

book/src/SUMMARY.md

@@ -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)

book/src/getting-started.md

@@ -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.
 

book/src/overview.md

@@ -1,20 +1,4 @@
----
+# Overview
-title: Home
-layout: default
-nav_order: 1
-permalink: /
----
-
-# Stabilizer
-{: .no_toc }
-
-## Table of Contents
-{: .no_toc .text-delta }
-
-1. TOC
-{:toc}
-
-## 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 |
+| [`dual-iir`](firmware/dual_iir/index.html) | Two channel biquad IIR filter |
-| [`lockin`]({{site.baseurl}}/firmware/lockin/index.html) | Lockin amplifier support various various reference sources |
+| [`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).

book/src/usage.md

@@ -1,17 +1,4 @@
----
+# Miniconf Run-time Settings
-title: Usage
-layout: default
-nav_order: 4
-permalink: /usage
----
-
-## Table of Contents
-{: .no_toc .text-delta }
-
-1. TOC
-{:toc}
-
-## 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.

docs/Gemfile

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

docs/Gemfile.lock

@@ -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

docs/README.md

@@ -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
-```

docs/Rakefile

@@ -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

docs/_config.yml

@@ -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