Switch to Just-the-Docs, fix formatting for new theme (#5)

* Change theme, add Gemfile

* Add headers to all docs, switch to more maintained theme, remove toc from index

* Better headers / sectioning

* Fix tables

.gitignore

@@ -52,4 +52,8 @@ GTAGS
 TAGS
 tags
 
-.idea
+.idea
+
+_site
+.jekyll-cache
+vendor

Gemfile

@@ -0,0 +1,8 @@
+source 'https://rubygems.org'
+
+gem 'jekyll'
+gem 'rake'
+gem 'webrick'
+gem 'jekyll-relative-links'
+gem 'jekyll-remote-theme'
+gem 'jekyll-seo-tag'

Gemfile.lock

@@ -0,0 +1,84 @@
+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.3)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0)
+    eventmachine (1.2.7)
+    ffi (1.15.5)
+    forwardable-extended (2.6.0)
+    http_parser.rb (0.8.0)
+    i18n (1.10.0)
+      concurrent-ruby (~> 1.0)
+    jekyll (4.2.1)
+      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-relative-links (0.6.1)
+      jekyll (>= 3.3, < 5.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.8.0)
+      jekyll (>= 3.8, < 5.0)
+    jekyll-watch (2.2.1)
+      listen (~> 3.0)
+    kramdown (2.3.1)
+      rexml
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
+    liquid (4.0.3)
+    listen (3.7.1)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    mercenary (0.4.0)
+    pathutil (0.16.2)
+      forwardable-extended (~> 2.6)
+    public_suffix (4.0.6)
+    rake (13.0.6)
+    rb-fsevent (0.11.1)
+    rb-inotify (0.10.1)
+      ffi (~> 1.0)
+    rexml (3.2.5)
+    rouge (3.28.0)
+    rubyzip (2.3.2)
+    safe_yaml (1.0.5)
+    sassc (2.4.0)
+      ffi (~> 1.9)
+    terminal-table (2.0.0)
+      unicode-display_width (~> 1.1, >= 1.1.1)
+    unicode-display_width (1.8.0)
+    webrick (1.7.0)
+
+PLATFORMS
+  x86_64-linux
+
+DEPENDENCIES
+  jekyll
+  jekyll-relative-links
+  jekyll-remote-theme
+  jekyll-seo-tag
+  rake
+  webrick
+
+BUNDLED WITH
+   2.2.33

README.md

@@ -9,6 +9,8 @@ Each lesson builds on the previous one. Most lessons end with exercises (with so
 
 This tutorial is under active development, if you want to participate - please read the [Contribution guide](docs/Contributions.md).
 
+A web version of this tutorial can also be found [here](https://maksimdrachov.github.io/zephyr-rtos-tutorial).
+
 ## Table of Contents
 
 - [x] **[Introduction](docs/Introduction.md)**

_config.yml

@@ -1 +1,18 @@
-theme: jekyll-theme-slate
+title: Zephyr Tutorial
+remote_theme: bedroesb/just-the-docs
+
+plugins:
+  - jekyll-relative-links
+  - jekyll-remote-theme
+  - jekyll-seo-tag
+
+callouts:
+  note:
+    title: Note
+    color: green
+  warning:
+    title: Warning
+    color: yellow
+  error:
+    title: Error
+    color: red

_includes/incomplete.md

@@ -0,0 +1,2 @@
+{: .warning}
+This section is incomplete. You can help by [contributing](https://github.com/maksimdrachov/zephyr-rtos-tutorial).

docs/Contributions.md

@@ -1,3 +1,9 @@
+---
+layout: post
+title: Contributing
+nav_order: 3
+---
+
 ## Contributing to the Zephyr RTOS Tutorial
 
 The general workflow is the following:

docs/Introduction.md

@@ -1,9 +1,15 @@
-## Zephyr Tutorial Introduction
+---
+layout: post
+title: Introduction
+nav_order: 1
+---
 
-*Why have I started writing this tutorial?*
+# Zephyr Tutorial Introduction
+
+## Why have I started writing this tutorial?
 
 When I started learning Zephyr (~June 2021) I noticed it was difficult to find a clear and comprehensive guide for n00bs like myself. As I was learning I made a Gihub repository with personal notes and useful links. Eventually I decided to write a comprehensive tutorial - to give back to the open source community and to help others that might want to learn Zephyr. 
 
-*Why on Github?*
+## Why on Github?
 
 As Zephyr is a relatively new project and still very much evolving, I thought it made sense to write this tutorial in an open source manner. Therefore as things change, and the project evolves, it will remain possible to keep the information up-to-date. If you come across any code that is not working, information that is invalid (or out-of-date),... don't hesitate to raise an issue or submit a PR. I hope that with the help of the Zephyr community this can become an entry-point for all beginners.

docs/Prerequisites.md

@@ -1,12 +1,18 @@
-## Prerequisites
+---
+layout: post
+title: Prerequisites
+nav_order: 2
+---
 
-### 1. [NUCLEO-F756ZG](https://www.st.com/en/evaluation-tools/nucleo-f756zg.html)
+# Prerequisites
+
+## 1. [NUCLEO-F756ZG](https://www.st.com/en/evaluation-tools/nucleo-f756zg.html)
 This is the board that we'll be using for the tutorial, since Zephyr is platform-agnostic you can also use whatever you have laying around, but the commands might look slitghtly different for you.
 
 [Zephyr supported boards](https://docs.zephyrproject.org/latest/boards/index.html#boards)
 
-### 2. [USB to Micro-USB Cable](https://www.google.com/search?q=micro+usb)
+## 2. [USB to Micro-USB Cable](https://www.google.com/search?q=micro+usb)
 This allows you to connect you Nucleo board through the debugger to your computer.
 
-### 3. [Ethernet Cable](https://www.google.com/search?q=ethernet)
+## 3. [Ethernet Cable](https://www.google.com/search?q=ethernet)
 If you want to learn about networking you'll need an ethernet cable and an ethernet port on your computer (or have access to the router).

docs/build-system/index.md

@@ -0,0 +1,6 @@
+---
+layout: post
+title: 'Lesson 13: Build System'
+has_children: true
+nav_order: 130
+---

docs/build-system/introduction.md

@@ -1,22 +1,28 @@
-## Build System
+---
+layout: post
+title: '13.1 Introduction'
+parent: 'Lesson 13: Build System'
+---
 
-*How does `west` work?*
+# Build System
+
+## How does `west` work?
 
 Every time you type `west build` the build process starts.
 
 The first stage is called **configuration** and uses CMake. During configuration, the CMakeLists.txt build scripts are executed. What this means is that the Cmake commands will be read and a list of files (source files, dependencies, external libraries,...) will be compiled to be passed on to your build system. If you configure something wrong in you CMakeLists (for example forget to include an external library), this will show up as an error during the build phase (since it won't be able to find the library once you `#include` it in some file). Important to mention as well: the settings you provide in your Kconfig will also affect which files/libraries get included. This means for example that if you require a TCP/IP stack and forget to turn on CONFIG_NETWORKING, you'll get an error saying that `#include <net/net_if.h>` can't be found. 
 
 The next stage is called the **build** stage. Cmake supports several build systems, but in our case we are only interested in Ninja and Make. Make is the 'old' build system; while Ninja is the newer, more efficient build system. These will execute the build scripts and recompile the application. As a developer we are often less interested in this stage, since it doesn't really affect the way our application works. 
 
-*What is Cmake?*
+## What is Cmake?
 
-*What is Make?*
+## What is Make?
 
-*What is Ninja?*
+## What is Ninja?
 
 Once you start to play with multiple libraries, it might be useful to read up on Make, Cmake and Ninja (in that order). See recommended reading below. For more basic applications, it will probably suffice to understand the examples discussed below.
 
-*How does a basic sample work?*
+## How does a basic sample work?
 
 A basic example of a CMakeLists.txt (samples/basic/blinky)
 
@@ -35,7 +41,7 @@ target_sources(app PRIVATE src/main.c)
 
 ![boilerplate](/images/build-system/boilerplate.png)
 
-*How does this work with more complex applications?*
+## How does this work with more complex applications?
 
 (samples/net/sockets/echo_client)
 
@@ -103,7 +109,7 @@ target_sources_ifdef(CONFIG_NET_VLAN app PRIVATE src/vlan.c)
 - target_sources: adds echo-client.c to our app, in the previous basic sample, this was main.c
 - target_sources_ifdef: depending on our Kconfig settings we'll be adding some additional files to our app.
 
-*How to import an external library?*
+## How to import an external library?
 
 (samples/application_development/external_lib)
 
@@ -180,7 +186,7 @@ target_link_libraries(app PUBLIC mylib_lib)
 
 ```
 
-*Recommended reading*
+## Recommended reading
 
 While reading "GNU Make Manual", keep the following in mind:
 

docs/build-system/next.md

@@ -1,4 +1,10 @@
-What's next? 
+---
+layout: post
+title: '13.2 Next?'
+parent: 'Lesson 13: Build System'
+---
+
+# What's next? 
 
 Now that you've hopefully become somewhat acquainted to the way Zephyr works it is really up to you to decide how this journey continues. In this final section I would like to give you some pointers as to how you might continue growing your skills:
 

docs/debugging/commands.md

@@ -1,3 +1,8 @@
+---
+layout: post
+title: '6.2 Commands'
+parent: 'Lesson 6: Debugging'
+---
 
 ## Runtime statistics
 The analysis is performed on demand when the application calls one of the following functions:

docs/debugging/exercise.md

@@ -1,3 +1,9 @@
+---
+layout: post
+title: '6.4 Exercise'
+parent: 'Lesson 6: Debugging'
+---
+
 ## Exercise 1: Multiple threads debugging
 
 Using the code from the previous section (time-slicing), we'll try to see how debugging works in VSCode.
@@ -61,4 +67,4 @@ west flash
 
 _Come back to this when I understand GDB better_
 
-
+{% include incomplete.md %}

docs/debugging/index.md

@@ -0,0 +1,6 @@
+---
+layout: post
+title: 'Lesson 6: Debugging'
+has_children: true
+nav_order: 60
+---

docs/debugging/introduction.md

@@ -1,12 +1,19 @@
-*What are some common debugging techniques and when to use them?*
+---
+layout: post
+title: '6.1 Introduction'
+parent: 'Lesson 6: Debugging'
+---
+
+# Introduction
+
+## What are some common debugging techniques and when to use them?
 
 The three most common debugging techniques we'll be discussing here are:
 - thread aware debugging (debug probe)
 - thread analysis
 - core dump
 
-*How does thread aware debugging work?*
-
+## How does thread aware debugging work?
 
 To enable thread-aware debugging you'll need to add the line shown below to `zephyr/boards/arm/nucleo_f756zg/support/openocd.cfg`
 
@@ -27,7 +34,7 @@ It is compatible with the following host debug tools:
 
 In this tutorial we'll be using OpenOCD.
 
-*How to use OpenOCD?*
+## How to use OpenOCD?
 
 OpenOCD is available by default on ST-Link and configured as the default flash and debug tool. Flash and debug can be done as follows:
 ```
@@ -39,15 +46,15 @@ west build -b nucleo_f756zg
 west debug
 ```
 
-*How does thread analysis work?*
+## How does thread analysis work?
 
 The thread analyzer module enables all the Zephyr options required to track the thread information, e.g. thread stack size usage and other runtime thread statistics.
 
 The analysis is performed on demand when the application calls thread_analyzer_run() or thread_analyzer_print().
 
 The output is put on the serial connection.
 
-*How does core dump work?*
+## How does core dump work?
 
 The core dump module enables dumping the CPU registers and memory content for offline debugging. This module is called when a fatal error is encountered, and the data is printed or stored to which backends are enabled. This core dump data can be fed into a custom made GDB server as a remote target for GDB. CPU registers, memory content and stack can be examined in the debugger.
 

docs/debugging/kconfig.md

@@ -1,6 +1,12 @@
+---
+layout: post
+title: '6.3 Kconfig'
+parent: 'Lesson 6: Debugging'
+---
+
 ## OpenOCD
 
-## Thread analyzer
+### Thread analyzer
 
 | CONFIG | Description |
 | --- | --- |
@@ -13,10 +19,7 @@
 | THREAD_NAME | enable this option in the kernel to print the name of the thread instead of its ID |
 | THREAD_RUNTIME_STATS | enable this option to print thread runtime data such as utilization (This options is automatically selected by THREAD_ANALYZER) |
 
-
-
-
-## Core dump
+### Core dump
 
 | CONFIG | Description |
 | --- | --- |