From 37688e70a3f9034e68c6b23459bc4b75e6635286 Mon Sep 17 00:00:00 2001 From: Ryan Summers Date: Mon, 9 Aug 2021 15:21:42 +0200 Subject: [PATCH 1/6] Adding mdbook-based user manual --- .github/workflows/ci.yml | 27 ++--- .github/workflows/release-docs.yml | 18 +++- .gitignore | 1 - book/.gitignore | 2 + book/README.md | 21 ++++ book/book.toml | 16 +++ book/src/SUMMARY.md | 7 ++ {docs => book/src}/assets/mqtt-explorer.png | Bin {docs => book/src}/assets/stabilizer-jtag.jpg | Bin {docs => book/src}/assets/stabilizer-logo.png | Bin {docs => book/src}/assets/stabilizer_pid.svg | 0 {docs/pages => book/src}/getting-started.md | 18 +--- docs/index.md => book/src/overview.md | 32 ++---- {docs/pages => book/src}/usage.md | 31 ++---- book/theme/favicon.png | Bin 0 -> 6279 bytes docs/Gemfile | 4 - docs/Gemfile.lock | 102 ------------------ docs/README.md | 20 ---- docs/Rakefile | 35 ------ docs/_config.yml | 18 ---- docs/favicon.ico | Bin 1150 -> 0 bytes 21 files changed, 90 insertions(+), 262 deletions(-) create mode 100644 book/.gitignore create mode 100644 book/README.md create mode 100644 book/book.toml create mode 100644 book/src/SUMMARY.md rename {docs => book/src}/assets/mqtt-explorer.png (100%) rename {docs => book/src}/assets/stabilizer-jtag.jpg (100%) rename {docs => book/src}/assets/stabilizer-logo.png (100%) rename {docs => book/src}/assets/stabilizer_pid.svg (100%) rename {docs/pages => book/src}/getting-started.md (94%) rename docs/index.md => book/src/overview.md (79%) rename {docs/pages => book/src}/usage.md (84%) create mode 100644 book/theme/favicon.png delete mode 100644 docs/Gemfile delete mode 100644 docs/Gemfile.lock delete mode 100644 docs/README.md delete mode 100644 docs/Rakefile delete mode 100644 docs/_config.yml delete mode 100644 docs/favicon.ico diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0a8b6e1..322ee56 100644 --- a/.github/workflows/ci.yml +++ b/.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: @@ -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 diff --git a/.github/workflows/release-docs.yml b/.github/workflows/release-docs.yml index 0816dad..89a5bf9 100644 --- a/.github/workflows/release-docs.yml +++ b/.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 + - run: | + working-directory: book + mv ../target/thumbv7em-none-eabihf/doc src/firmware + mdbook build - uses: peaceiris/actions-gh-pages@v3.8.0 with: diff --git a/.gitignore b/.gitignore index a6eef6e..ea8c4bf 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1 @@ /target -docs/_site/ diff --git a/book/.gitignore b/book/.gitignore new file mode 100644 index 0000000..72aca82 --- /dev/null +++ b/book/.gitignore @@ -0,0 +1,2 @@ +stabilizer-manual +src/firmware diff --git a/book/README.md b/book/README.md new file mode 100644 index 0000000..ed60514 --- /dev/null +++ b/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`. diff --git a/book/book.toml b/book/book.toml new file mode 100644 index 0000000..03fb06a --- /dev/null +++ b/book/book.toml @@ -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] diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md new file mode 100644 index 0000000..f3717bd --- /dev/null +++ b/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) diff --git a/docs/assets/mqtt-explorer.png b/book/src/assets/mqtt-explorer.png similarity index 100% rename from docs/assets/mqtt-explorer.png rename to book/src/assets/mqtt-explorer.png diff --git a/docs/assets/stabilizer-jtag.jpg b/book/src/assets/stabilizer-jtag.jpg similarity index 100% rename from docs/assets/stabilizer-jtag.jpg rename to book/src/assets/stabilizer-jtag.jpg diff --git a/docs/assets/stabilizer-logo.png b/book/src/assets/stabilizer-logo.png similarity index 100% rename from docs/assets/stabilizer-logo.png rename to book/src/assets/stabilizer-logo.png diff --git a/docs/assets/stabilizer_pid.svg b/book/src/assets/stabilizer_pid.svg similarity index 100% rename from docs/assets/stabilizer_pid.svg rename to book/src/assets/stabilizer_pid.svg diff --git a/docs/pages/getting-started.md b/book/src/getting-started.md similarity index 94% rename from docs/pages/getting-started.md rename to book/src/getting-started.md index 8603b2e..81eb5fe 100644 --- a/docs/pages/getting-started.md +++ b/book/src/getting-started.md @@ -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. -![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 +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. -![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. diff --git a/docs/index.md b/book/src/overview.md similarity index 79% rename from docs/index.md rename to book/src/overview.md index 6aaa6ad..f987175 100644 --- a/docs/index.md +++ b/book/src/overview.md @@ -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). diff --git a/docs/pages/usage.md b/book/src/usage.md similarity index 84% rename from docs/pages/usage.md rename to book/src/usage.md index d6f2c1d..20084f5 100644 --- a/docs/pages/usage.md +++ b/book/src/usage.md @@ -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//`, where `` is the name of the application and `` 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. diff --git a/book/theme/favicon.png b/book/theme/favicon.png new file mode 100644 index 0000000000000000000000000000000000000000..e1c3dda6871ab681d2f2965efb55e73d574b8c48 GIT binary patch literal 6279 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 z z-h;zM?{r67@Y7FSkQ^80WR)|TojGBH*J*;@U2T$<7!;n=xj&)mOb^lmky@2;VO*NY tieZ;UymCe3&MPAS>m_gBq5dg6JfuwVP%F4Bp}YhDs3>YEl*^e1{|^f7!%qMJ literal 0 HcmV?d00001 diff --git a/docs/Gemfile b/docs/Gemfile deleted file mode 100644 index e18d92a..0000000 --- a/docs/Gemfile +++ /dev/null @@ -1,4 +0,0 @@ -source 'https://rubygems.org' -gem "just-the-docs" -gem "jekyll-remote-theme" -gem "html-proofer" diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock deleted file mode 100644 index b8495b8..0000000 --- a/docs/Gemfile.lock +++ /dev/null @@ -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 diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 0d5ddec..0000000 --- a/docs/README.md +++ /dev/null @@ -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 -``` diff --git a/docs/Rakefile b/docs/Rakefile deleted file mode 100644 index dc5ab2f..0000000 --- a/docs/Rakefile +++ /dev/null @@ -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 diff --git a/docs/_config.yml b/docs/_config.yml deleted file mode 100644 index a7901db..0000000 --- a/docs/_config.yml +++ /dev/null @@ -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 diff --git a/docs/favicon.ico b/docs/favicon.ico deleted file mode 100644 index a6cbb9e75c3edc9c71cb69eac9c7b32874c82676..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1150 zcmbu8%WD%+6o*ektqY4yt#?X`3s<$oMFnvsN)i#ZAZU|J5-Dnhq_OBCsl{O0=AB8V zNrZ}u3xzJKt`z?Pw}MMST=*}D&y^t5?t& z1GHb^2l{vT-N3H^4z!80h;0(^v*99*WRJU*|eUA_HxlUZ|Jx{zWJ|*Vm{QepLn#DbJ>-S?9dQ9Wzg&`P( zc{EE<K-^}bgw~PMtenZdzr)P!s*fLePMkS~T15l3INab9{3r=;JUkF0iKW Date: Mon, 9 Aug 2021 15:22:57 +0200 Subject: [PATCH 2/6] Updating authors --- book/book.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/book.toml b/book/book.toml index 03fb06a..bbdac8a 100644 --- a/book/book.toml +++ b/book/book.toml @@ -1,5 +1,5 @@ [book] -authors = ["Ryan Summers"] +authors = ["Ryan Summers", "Robert Jördens"] language = "en" multilingual = false src = "src" From e0341620dabce51cdc092db1e2b098f3039062ee Mon Sep 17 00:00:00 2001 From: Ryan Summers Date: Mon, 9 Aug 2021 15:23:47 +0200 Subject: [PATCH 3/6] Removing stale markdown --- book/src/getting-started.md | 1 - 1 file changed, 1 deletion(-) diff --git a/book/src/getting-started.md b/book/src/getting-started.md index 81eb5fe..f8c4205 100644 --- a/book/src/getting-started.md +++ b/book/src/getting-started.md @@ -1,5 +1,4 @@ # 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 From c30a222da2a2031f9fd519bda8e41814f9c43e84 Mon Sep 17 00:00:00 2001 From: Ryan Summers Date: Mon, 9 Aug 2021 15:26:24 +0200 Subject: [PATCH 4/6] Fixing workflow --- .github/workflows/release-docs.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/release-docs.yml b/.github/workflows/release-docs.yml index 89a5bf9..80b14b9 100644 --- a/.github/workflows/release-docs.yml +++ b/.github/workflows/release-docs.yml @@ -26,8 +26,7 @@ jobs: uses: actions-rs/cargo@v1 with: command: install - args: | - mdbook-linkcheck + args: mdbook-linkcheck - uses: peaceiris/actions-mdbook@v1 with: @@ -38,8 +37,9 @@ jobs: command: doc args: --no-deps -p miniconf -p ad9959 -p stabilizer -p dsp - - run: | - working-directory: book + - name: Build Book + working-directory: book + run: mv ../target/thumbv7em-none-eabihf/doc src/firmware mdbook build From 52dbe0113618ae175a6632e1423209903b2ffca3 Mon Sep 17 00:00:00 2001 From: Ryan Summers Date: Mon, 9 Aug 2021 15:30:09 +0200 Subject: [PATCH 5/6] Installing linkcheck for CI --- .github/workflows/ci.yml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 322ee56..0051d31 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -108,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: From a1fb1200105eeb5cf73cfc4b1f4235a10d7d1833 Mon Sep 17 00:00:00 2001 From: Ryan Summers Date: Mon, 9 Aug 2021 15:36:58 +0200 Subject: [PATCH 6/6] Fixing gitignore --- book/.gitignore | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/.gitignore b/book/.gitignore index 72aca82..d8dc208 100644 --- a/book/.gitignore +++ b/book/.gitignore @@ -1,2 +1,2 @@ -stabilizer-manual -src/firmware +/stabilizer-manual/ +/src/firmware/