implement HTML API reference autogeneration

This adds a jinja template to generate markdown files (with lots of HTML mixed in) from YAML using the existing interface_generator.py script. The docs website layout files are modified to incorporate the new documentation. While previously Github Pages was automatically running Jekyll on the docs folder, this commit adds a custom Github workflow to compile and deploy the website to facilitate the custom markdown generation step before Jekyll runs.
2026-08-18 09:29:03 +08:00 · 2020-06-10 23:03:07 +02:00
parent b88f66ab99
commit 426236dff1
11 changed files with 540 additions and 185 deletions
@@ -0,0 +1,67 @@
+name: Build and publish HTML documentation website
+
+on:
+  push:
+    branches: [ feature/doc_autogen ]
+
+jobs:
+  jekyll:
+    runs-on: ubuntu-16.04
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Setup Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: '3.x'
+
+    # Use GitHub Actions' cache for ruby and python packages to shorten build times and decrease load on servers
+    - name: Cache gems
+      uses: actions/cache@v2
+      with:
+        path: docs/vendor/bundle
+        key: ${{ runner.os }}-gems-${{ hashFiles('docs/Gemfile.lock') }}
+        restore-keys: |
+          ${{ runner.os }}-gems-
+    
+    - name: Cache pip
+      uses: actions/cache@v2
+      with:
+        path: ~/.cache/pip
+        key: ${{ runner.os }}-pip-PyYAML-Jinja2-jsonschema
+        restore-keys: |
+          ${{ runner.os }}-pip-
+          ${{ runner.os }}-
+
+    - name: Install Python dependencies
+      run: pip install PyYAML Jinja2 jsonschema
+
+    # Autogenerate the API reference .md files in the python in the python/python3 container
+    - name: Autogenerate the API reference .md files in the python container
+      run: |
+        mkdir -p docs/_api docs/_includes
+        python Firmware/interface_generator_stub.py --definitions Firmware/odrive-interface.yaml --template docs/_layouts/api_documentation_template.j2 --outputs docs/_api/#.md
+        python Firmware/interface_generator_stub.py --definitions Firmware/odrive-interface.yaml --template docs/_layouts/api_index_template.j2 --output docs/_includes/apiindex.html
+    
+    - name: Build the site in the jekyll/builder container
+      run: |
+        docker run \
+        -v ${{ github.workspace }}:/srv/jekyll -e PAGES_REPO_NWO=${GITHUB_REPOSITORY} \
+        ruby:2.7-buster /bin/sh -c "
+          chmod 777 /srv/jekyll/docs && \
+          cd /srv/jekyll/docs && \
+          bundle config path vendor/bundle && \
+          bundle install && \
+          JEKYLL_ENV=production bundle exec jekyll build
+        "
+        touch .nojekyll
+
+    - name: Push to documentation branch
+      run: |
+        git config user.name "${GITHUB_ACTOR}"
+        git config user.email "${GITHUB_ACTOR}@users.noreply.github.com"
+        git add -f docs/_site
+        git commit -m "jekyll build from Action ${GITHUB_SHA}"
+        git push --force origin HEAD:${REMOTE_BRANCH}
+      env:
+        REMOTE_BRANCH: gh-pages
@@ -24,9 +24,6 @@ coverage.xml
 # Django stuff:
 *.log

-# Sphinx documentation
-docs/_build/
-
 # PyBuilder
 target/

@@ -37,10 +34,18 @@ target/
 .tup
 tup.config

-docs/ruby-bundle
-docs/_site
-docs/.bundle
-docs/Gemfile.lock
+# Sphinx documentation
+/docs/_build/
+
+# Autogenerated API reference
+/docs/_api
+/docs/_includes/apiindex.html
+
+# Jekyll HTML documention and artifacts
+/docs/ruby-bundle
+/docs/_site
+/docs/.bundle/config
+/docs/.jekyll-metadata


 *.exe
@@ -623,13 +623,17 @@ def tokenize(text, interface, interface_transform, value_type_transform, attribu
        token_list = split_name(token)

        # Check if this is an attribute reference
-        attr_intf = interface
-        for name in token_list:
-            if not name in attr_intf['attributes']:
-                attr = None
-                break
-            attr = attr_intf['attributes'][name]
-            attr_intf = attr['type']
+        scope = interface
+        attr = None
+        while attr is None and not scope is None:
+            attr_intf = scope
+            for name in token_list:
+                if not name in attr_intf['attributes']:
+                    attr = None
+                    break
+                attr = attr_intf['attributes'][name]
+                attr_intf = attr['type']
+            scope = scope.get('parent', None)
        
        if not attr is None:
            return attribute_transform(token, attr)
@@ -648,6 +652,7 @@ env.filters['first'] = lambda x: next(iter(x))
 env.filters['skip_first'] = lambda x: list(x)[1:]
 env.filters['to_c_string'] = lambda x: '\n'.join(('"' + line.replace('"', '\\"') + '"') for line in json.dumps(x, separators=(',', ':')).replace('{"name"', '\n{"name"').split('\n'))
 env.filters['tokenize'] = tokenize
+env.filters['diagonalize'] = lambda lst: [lst[:i + 1] for i in range(len(lst))]

 template = env.from_string(template_file.read())

@@ -1,55 +1,57 @@
 GEM
  remote: https://rubygems.org/
  specs:
-    activesupport (4.2.9)
-      i18n (~> 0.7)
+    activesupport (6.0.3.1)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
      minitest (~> 5.1)
-      thread_safe (~> 0.3, >= 0.3.4)
      tzinfo (~> 1.1)
-    addressable (2.5.2)
-      public_suffix (>= 2.0.2, < 4.0)
+      zeitwerk (~> 2.2, >= 2.2.2)
+    addressable (2.7.0)
+      public_suffix (>= 2.0.2, < 5.0)
    coffee-script (2.4.1)
      coffee-script-source
      execjs
    coffee-script-source (1.11.1)
    colorator (1.1.0)
-    commonmarker (0.17.9)
+    commonmarker (0.17.13)
      ruby-enum (~> 0.5)
-    concurrent-ruby (1.0.5)
+    concurrent-ruby (1.1.6)
+    dnsruby (1.61.3)
+      addressable (~> 2.5)
    em-websocket (0.5.1)
      eventmachine (>= 0.12.9)
      http_parser.rb (~> 0.6.0)
-    ethon (0.11.0)
+    ethon (0.12.0)
      ffi (>= 1.3.0)
-    eventmachine (1.2.5)
+    eventmachine (1.2.7)
    execjs (2.7.0)
-    faraday (0.14.0)
+    faraday (1.0.1)
      multipart-post (>= 1.2, < 3)
-    ffi (1.9.24)
+    ffi (1.12.2)
    forwardable-extended (2.6.0)
-    gemoji (3.0.0)
-    github-pages (181)
-      activesupport (= 4.2.9)
-      github-pages-health-check (= 1.4.0)
-      jekyll (= 3.7.4)
-      jekyll-avatar (= 0.5.0)
+    gemoji (3.0.1)
+    github-pages (206)
+      github-pages-health-check (= 1.16.1)
+      jekyll (= 3.8.7)
+      jekyll-avatar (= 0.7.0)
      jekyll-coffeescript (= 1.1.1)
-      jekyll-commonmark-ghpages (= 0.1.5)
+      jekyll-commonmark-ghpages (= 0.1.6)
      jekyll-default-layout (= 0.1.4)
-      jekyll-feed (= 0.9.3)
+      jekyll-feed (= 0.13.0)
      jekyll-gist (= 1.5.0)
-      jekyll-github-metadata (= 2.9.4)
-      jekyll-mentions (= 1.3.0)
-      jekyll-optional-front-matter (= 0.3.0)
+      jekyll-github-metadata (= 2.13.0)
+      jekyll-mentions (= 1.5.1)
+      jekyll-optional-front-matter (= 0.3.2)
      jekyll-paginate (= 1.1.0)
-      jekyll-readme-index (= 0.2.0)
-      jekyll-redirect-from (= 0.13.0)
-      jekyll-relative-links (= 0.5.3)
-      jekyll-remote-theme (= 0.2.3)
+      jekyll-readme-index (= 0.3.0)
+      jekyll-redirect-from (= 0.15.0)
+      jekyll-relative-links (= 0.6.1)
+      jekyll-remote-theme (= 0.4.1)
      jekyll-sass-converter (= 1.5.2)
-      jekyll-seo-tag (= 2.4.0)
-      jekyll-sitemap (= 1.2.0)
-      jekyll-swiss (= 0.4.0)
+      jekyll-seo-tag (= 2.6.1)
+      jekyll-sitemap (= 1.4.0)
+      jekyll-swiss (= 1.0.0)
      jekyll-theme-architect (= 0.1.1)
      jekyll-theme-cayman (= 0.1.1)
      jekyll-theme-dinky (= 0.1.1)
@@ -59,33 +61,32 @@ GEM
      jekyll-theme-midnight (= 0.1.1)
      jekyll-theme-minimal (= 0.1.1)
      jekyll-theme-modernist (= 0.1.1)
-      jekyll-theme-primer (= 0.5.3)
+      jekyll-theme-primer (= 0.5.4)
      jekyll-theme-slate (= 0.1.1)
      jekyll-theme-tactile (= 0.1.1)
      jekyll-theme-time-machine (= 0.1.1)
-      jekyll-titles-from-headings (= 0.5.1)
-      jemoji (= 0.9.0)
-      kramdown (= 1.16.2)
-      liquid (= 4.0.0)
-      listen (= 3.1.5)
+      jekyll-titles-from-headings (= 0.5.3)
+      jemoji (= 0.11.1)
+      kramdown (= 1.17.0)
+      liquid (= 4.0.3)
      mercenary (~> 0.3)
-      minima (= 2.4.0)
-      nokogiri (>= 1.8.5, < 2.0)
-      rouge (= 2.2.1)
+      minima (= 2.5.1)
+      nokogiri (>= 1.10.4, < 2.0)
+      rouge (= 3.19.0)
      terminal-table (~> 1.4)
-    github-pages-health-check (1.4.0)
+    github-pages-health-check (1.16.1)
      addressable (~> 2.3)
-      net-dns (~> 0.8)
+      dnsruby (~> 1.60)
      octokit (~> 4.0)
-      public_suffix (~> 2.0)
+      public_suffix (~> 3.0)
      typhoeus (~> 1.3)
-    html-pipeline (2.7.1)
+    html-pipeline (2.13.0)
      activesupport (>= 2)
-      nokogiri (>= 1.8.5)
+      nokogiri (>= 1.4)
    http_parser.rb (0.6.0)
    i18n (0.9.5)
      concurrent-ruby (~> 1.0)
-    jekyll (3.7.4)
+    jekyll (3.8.7)
      addressable (~> 2.4)
      colorator (~> 1.0)
      em-websocket (~> 0.5)
@@ -98,51 +99,50 @@ GEM
      pathutil (~> 0.9)
      rouge (>= 1.7, < 4)
      safe_yaml (~> 1.0)
-    jekyll-avatar (0.5.0)
-      jekyll (~> 3.0)
+    jekyll-avatar (0.7.0)
+      jekyll (>= 3.0, < 5.0)
    jekyll-coffeescript (1.1.1)
      coffee-script (~> 2.2)
      coffee-script-source (~> 1.11.1)
-    jekyll-commonmark (1.2.0)
+    jekyll-commonmark (1.3.1)
      commonmarker (~> 0.14)
-      jekyll (>= 3.0, < 4.0)
-    jekyll-commonmark-ghpages (0.1.5)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-commonmark-ghpages (0.1.6)
      commonmarker (~> 0.17.6)
-      jekyll-commonmark (~> 1)
-      rouge (~> 2)
+      jekyll-commonmark (~> 1.2)
+      rouge (>= 2.0, < 4.0)
    jekyll-default-layout (0.1.4)
      jekyll (~> 3.0)
-    jekyll-feed (0.9.3)
-      jekyll (~> 3.3)
+    jekyll-feed (0.13.0)
+      jekyll (>= 3.7, < 5.0)
    jekyll-gist (1.5.0)
      octokit (~> 4.2)
-    jekyll-github-metadata (2.9.4)
-      jekyll (~> 3.1)
+    jekyll-github-metadata (2.13.0)
+      jekyll (>= 3.4, < 5.0)
      octokit (~> 4.0, != 4.4.0)
-    jekyll-mentions (1.3.0)
-      activesupport (~> 4.0)
+    jekyll-mentions (1.5.1)
      html-pipeline (~> 2.3)
-      jekyll (~> 3.0)
-    jekyll-optional-front-matter (0.3.0)
-      jekyll (~> 3.0)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-optional-front-matter (0.3.2)
+      jekyll (>= 3.0, < 5.0)
    jekyll-paginate (1.1.0)
-    jekyll-readme-index (0.2.0)
-      jekyll (~> 3.0)
-    jekyll-redirect-from (0.13.0)
-      jekyll (~> 3.3)
-    jekyll-relative-links (0.5.3)
-      jekyll (~> 3.3)
-    jekyll-remote-theme (0.2.3)
-      jekyll (~> 3.5)
-      rubyzip (>= 1.3.0, < 3.0)
-      typhoeus (>= 0.7, < 2.0)
+    jekyll-readme-index (0.3.0)
+      jekyll (>= 3.0, < 5.0)
+    jekyll-redirect-from (0.15.0)
+      jekyll (>= 3.3, < 5.0)
+    jekyll-relative-links (0.6.1)
+      jekyll (>= 3.3, < 5.0)
+    jekyll-remote-theme (0.4.1)
+      addressable (~> 2.0)
+      jekyll (>= 3.5, < 5.0)
+      rubyzip (>= 1.3.0)
    jekyll-sass-converter (1.5.2)
      sass (~> 3.4)
-    jekyll-seo-tag (2.4.0)
-      jekyll (~> 3.3)
-    jekyll-sitemap (1.2.0)
-      jekyll (~> 3.3)
-    jekyll-swiss (0.4.0)
+    jekyll-seo-tag (2.6.1)
+      jekyll (>= 3.3, < 5.0)
+    jekyll-sitemap (1.4.0)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-swiss (1.0.0)
    jekyll-theme-architect (0.1.1)
      jekyll (~> 3.5)
      jekyll-seo-tag (~> 2.0)
@@ -170,8 +170,8 @@ GEM
    jekyll-theme-modernist (0.1.1)
      jekyll (~> 3.5)
      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-primer (0.5.3)
-      jekyll (~> 3.5)
+    jekyll-theme-primer (0.5.4)
+      jekyll (> 3.5, < 5.0)
      jekyll-github-metadata (~> 2.9)
      jekyll-seo-tag (~> 2.0)
    jekyll-theme-slate (0.1.1)
@@ -183,62 +183,60 @@ GEM
    jekyll-theme-time-machine (0.1.1)
      jekyll (~> 3.5)
      jekyll-seo-tag (~> 2.0)
-    jekyll-titles-from-headings (0.5.1)
-      jekyll (~> 3.3)
-    jekyll-watch (2.0.0)
+    jekyll-titles-from-headings (0.5.3)
+      jekyll (>= 3.3, < 5.0)
+    jekyll-watch (2.2.1)
      listen (~> 3.0)
-    jemoji (0.9.0)
-      activesupport (~> 4.0, >= 4.2.9)
+    jemoji (0.11.1)
      gemoji (~> 3.0)
      html-pipeline (~> 2.2)
-      jekyll (~> 3.0)
-    kramdown (1.16.2)
-    liquid (4.0.0)
-    listen (3.1.5)
-      rb-fsevent (~> 0.9, >= 0.9.4)
-      rb-inotify (~> 0.9, >= 0.9.7)
-      ruby_dep (~> 1.2)
+      jekyll (>= 3.0, < 5.0)
+    kramdown (1.17.0)
+    liquid (4.0.3)
+    listen (3.2.1)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
    mercenary (0.3.6)
-    mini_portile2 (2.3.0)
-    minima (2.4.0)
-      jekyll (~> 3.5)
+    mini_portile2 (2.4.0)
+    minima (2.5.1)
+      jekyll (>= 3.5, < 5.0)
      jekyll-feed (~> 0.9)
      jekyll-seo-tag (~> 2.1)
-    minitest (5.11.3)
-    multipart-post (2.0.0)
-    net-dns (0.8.0)
-    nokogiri (>= 1.8.5)
-      mini_portile2 (~> 2.3.0)
-    octokit (4.8.0)
+    minitest (5.14.1)
+    multipart-post (2.1.1)
+    nokogiri (1.10.9)
+      mini_portile2 (~> 2.4.0)
+    octokit (4.18.0)
+      faraday (>= 0.9)
      sawyer (~> 0.8.0, >= 0.5.3)
-    pathutil (0.16.1)
+    pathutil (0.16.2)
      forwardable-extended (~> 2.6)
-    public_suffix (2.0.5)
-    rb-fsevent (0.10.3)
-    rb-inotify (0.9.10)
-      ffi (>= 0.5.0, < 2)
-    rouge (2.2.1)
-    ruby-enum (0.7.2)
+    public_suffix (3.1.1)
+    rb-fsevent (0.10.4)
+    rb-inotify (0.10.1)
+      ffi (~> 1.0)
+    rouge (3.19.0)
+    ruby-enum (0.8.0)
      i18n
-    ruby_dep (1.5.0)
-    rubyzip (1.3.0)
-    safe_yaml (1.0.4)
-    sass (3.5.6)
+    rubyzip (2.3.0)
+    safe_yaml (1.0.5)
+    sass (3.7.4)
      sass-listen (~> 4.0.0)
    sass-listen (4.0.0)
      rb-fsevent (~> 0.9, >= 0.9.4)
      rb-inotify (~> 0.9, >= 0.9.7)
-    sawyer (0.8.1)
-      addressable (>= 2.3.5, < 2.6)
-      faraday (~> 0.8, < 1.0)
+    sawyer (0.8.2)
+      addressable (>= 2.3.5)
+      faraday (> 0.8, < 2.0)
    terminal-table (1.8.0)
      unicode-display_width (~> 1.1, >= 1.1.1)
    thread_safe (0.3.6)
-    typhoeus (1.3.0)
+    typhoeus (1.4.0)
      ethon (>= 0.9.0)
-    tzinfo (1.2.5)
+    tzinfo (1.2.7)
      thread_safe (~> 0.1)
-    unicode-display_width (1.3.0)
+    unicode-display_width (1.7.0)
+    zeitwerk (2.3.0)

 PLATFORMS
  ruby
@@ -248,4 +246,4 @@ DEPENDENCIES
  jekyll-redirect-from

 BUNDLED WITH
-   1.16.1
+   2.1.4
@@ -1,5 +1,8 @@
 theme: jekyll-theme-minimal
-exclude: [ruby-bundle]
+exclude: [ruby-bundle, vendor]
 plugins:
  - jekyll-redirect-from
 google_analytics: UA-93396600-3
+collections:
+  api:
+    output: true
@@ -3,34 +3,37 @@
 # https://jekyllrb.com/tutorials/navigation/#scenario-8-retrieving-items-based-on-front-matter-properties

 sections:
-  - title: For Users
+  - title: General
    docs:
      - title: Getting Started
        url: /
      - title: ODrive Tool
-        url: odrivetool
+        url: /odrivetool
      - title: Parameters & Commands
-        url: commands
+        url: /commands
      - title: Interfaces
-        url: interfaces
+        url: /interfaces
      - title: Encoders
-        url: encoders
+        url: /encoders
      - title: Homing & Endstops
-        url: endstops
+        url: /endstops
      - title: Control & Tuning
-        url: control
-      - title: Hoverboard Guide
-        url: hoverboard
+        url: /control
      - title: Troubleshooting
-        url: troubleshooting
+        url: /troubleshooting
+  - title: Tutorials
+    docs:
+      - title: Hoverboard Guide
+        url: /hoverboard
+  - title: API Reference
  - title: For ODrive Developers
    docs:
      - title: Firmware Developer Guide
-        url: developer-guide
+        url: /developer-guide
      - title: Configuring Visual Studio Code
-        url: configuring-vscode
+        url: /configuring-vscode
      - title: Configuring Eclipse
-        url: configuring-eclipse
+        url: /configuring-eclipse
  - title: Component Guides
    docs:
      - title: Motor Guide
@@ -0,0 +1,148 @@
+---
+title: '[% if interface %][[interface.fullname]][% else %][[enum.fullname]][% endif %]'
+layout: default
+edit_url: 'Firmware/odrive-interface.yaml'
+download:
+  url: 'Firmware/odrive-interface.yaml'
+  text: 'download as YAML'
+---
+
+[%- macro interface_ref(type) -%]
+**[['[']]<span [% if type.brief %]title="[[type.brief]]"[% endif %]>[[type.name]]</span>[[']']]([[type.fullname | lower]])**
+[%- endmacro %]
+
+[%- macro value_type_ref(type) -%]
+[%- if type.builtin %]
+**<span title="C type: [[type.c_name]], Python type: [[type.py_type]]">[[type.name]]</span>**
+[%- else %]
+**[['[']]<span [% if type.brief %]title="[[type.brief]]"[% endif %]>[[type.name]]</span>[[']']]([[type.fullname | lower]])**
+[%- endif %]
+[%- endmacro %]
+
+[% macro attr_ref(token, attr) -%]
+**[['[']]<span [% if attr.brief %]title="[[attr.brief]]"[% endif %]>[[token]]</span>[[']']]([[attr.parent.fullname | lower]]#[[attr.name]])**
+[%- endmacro %]
+
+[% if interface %]
+[% set scope = interface %]
+[% else %]
+[% set scope = enum.parent %]
+[% endif %]
+
+[%- macro doc_tokenize(text) %][[ text | tokenize(scope, interface_ref, value_type_ref, attr_ref) ]][% endmacro %]
+
+[%- macro status_badge(status) %]
+[%- if status == 'experimental' %]
+<span style="border: 1px solid; border-radius: 3px; padding: 1px 10px; color: #c35400; float: right;" title="This feature is still experimental. It may be buggy or change later. Use with caution.">Experimental</span>
+[%- endif %]
+[%- if status == 'deprecated' %]
+<span style="border: 1px solid; border-radius: 3px; padding: 1px 10px; color: #c35400; float: right;" title="This feature is deprecated and may be removed in future versions.">Deprecated</span>
+[%- endif %]
+[%- endmacro %]
+
+[%- macro breadcrumbs(title) %]
+# [% for item in title.split('.') | diagonalize -%]
+<a href="[[item | join('.') | lower]]">[[item[-1]]]</a>
+[%- if not loop.last %]<span style="font-size: x-large;opacity: 50%;">&ensp;&#x3009;</span>[% endif %]
+[%- endfor %]
+[%- endmacro %]
+
+[% if interface %]
+
+[[breadcrumbs(interface.fullname)]]
+
+[%- if interface.doc or interface.brief %]
+[[doc_tokenize(interface.brief)]][% if interface.brief and interface.doc %]
+
+[% endif %][[doc_tokenize(interface.doc)]]
+[%- endif %]
+
+## Attributes
+
+[% if interface.attributes %]
+[% for attr in interface.attributes.values() %]
+[%- if attr.type.purename == 'fibre.Property' %]
+<a name="[[attr.name]]"></a><span style="font-size: large;"><code markdown="span">[[attr.name]] - [[value_type_ref(attr.type.value_type)]]</code></span>&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-size: small;">_([[attr.type.mode]] property)_</span>
+[%- else %]
+<a name="[[attr.name]]"></a><span style="font-size: large;"><code markdown="span">[[attr.name]] - [[interface_ref(attr.type)]]</code></span>
+[%- endif %]
+[[-status_badge(attr.status)]]
+
+<ul markdown="block">
+[% if attr.doc or attr.brief %]
+[[doc_tokenize(attr.brief)]][% if attr.brief and attr.doc %]
+
+[% endif %][%- if attr.unit %]
+
+**Unit:** [[attr.unit]]
+
+[% endif %][[doc_tokenize(attr.doc)]]
+[%- else %]
+_No description_
+[%- endif %]
+</ul>
+[% endfor %]
+[% else %]
+This interface has no attributes.
+[% endif %]
+
+## Functions
+
+[% if interface.functions %]
+[% for function in interface.functions.values() %]
+<a name="[[function.name]]"></a><span style="font-size: large;"><code markdown="span">[[function.name]]([% for arg in function.in.values() | skip_first %][[arg.name]]: [[value_type_ref(arg.type)]][[', ' if not loop.last]][% endfor %])[[' -> ' if function.out]][% for arg in function.out.values() %][[arg.name]]: [[value_type_ref(arg.type)]][[', ' if not loop.last]][% endfor %]</code></span>
+
+<ul markdown="block">
+[% if function.doc or function.brief %]
+[[doc_tokenize(function.brief)]][% if function.brief and function.doc %]
+
+[% endif %][[doc_tokenize(function.doc)]]
+[%- else %]
+_No description_
+[%- endif %]
+[% if function.in.values() | skip_first %]
+**Inputs:**
+[%- for arg in function.in.values() | skip_first %]
+ - `[[arg.name]]`: [% if arg.doc %][[doc_tokenize(arg.doc)]][% else %]&nbsp;_No description_[% endif %]
+[%- endfor %]
+[%- endif %]
+[% if function.out.values() %]
+**Outputs:**
+[%- for arg in function.out.values() %]
+ - `[[arg.name]]`: [% if arg.doc %][[doc_tokenize(arg.doc)]][% else %]&nbsp;_No description_[% endif %]
+[%- endfor %]
+[%- endif %]
+</ul>
+[% endfor %]
+[% else %]
+This interface has no functions.
+[% endif %]
+
+[% else %]
+
+[[breadcrumbs(enum.fullname)]]
+
+[%- if enum.doc or enum.brief %]
+[[doc_tokenize(enum.brief)]][% if enum.brief and enum.doc %]
+
+[% endif %][[doc_tokenize(enum.doc)]]
+[%- endif %]
+
+## [% if enum.is_flags %]Flags[% else %]Values[% endif %]
+
+[% for k, value in enum['values'].items() %]
+<a name="[[value.name]]"></a><span style="font-size: large;"><code markdown="span">[[(enum.name + value.name) | to_macro_case]]</code>&ensp;&ndash;&ensp;[% if enum.is_flags %]0x[['%08x' | format(value.value)]][% else %][[value.value]][% endif %]</span>
+[[-status_badge(value.status)]]
+
+<ul markdown="block">
+[% if value.doc or value.brief %]
+[[doc_tokenize(value.brief)]][% if value.brief and value.doc %]
+
+[% endif %][[doc_tokenize(value.doc)]]
+[%- else %]
+_No description_
+[%- endif %]
+</ul>
+[% endfor %]
+
+[% endif %]
@@ -0,0 +1,29 @@
+[%- macro dump_interfaces(interfaces) %]
+[%- for intf in interfaces %]
+[%- if intf.interfaces or intf.value_types %]
+<li>
+{% assign myvar = (page.title + '.') | split: "[[intf.fullname + '.']]" %}
+  <input id="chk-[[intf.fullname]]" type="checkbox" {% if myvar[0] == "" %}checked{% endif %} hidden />
+  <p class="navitem{% if page.title == "[[intf.fullname]]" %} currentitem{% endif %}"><label for="chk-[[intf.fullname]]" class="chevron"></label><a href="{{site.baseurl}}/api/[[intf.fullname | lower]]">[[intf.name]]</a></p>
+  <ul class="expandable-list">
+[[dump_interfaces(intf.interfaces) | indent(4)]]
+[[dump_value_types(intf.enums) | indent(4)]]
+  </ul>
+</li>
+[%- else %]
+<li>
+  <p style="padding-left: 27px;" class="navitem{% if page.title == "[[intf.fullname]]" %} currentitem{% endif %}"><a href="{{site.baseurl}}/api/[[intf.fullname | lower]]">[[intf.name]]</a></p>
+</li>
+[%- endif %]
+[%- endfor %]
+[%- endmacro %]
+
+[%- macro dump_value_types(value_types) %]
+[%- for enum in value_types %]
+<li>
+  <p style="padding-left: 27px;" class="navitem{% if page.title == "[[enum.fullname]]" %} currentitem{% endif %}"><a href="{{site.baseurl}}/api/[[enum.fullname | lower]]">[[enum.name]]</a></p>
+</li>
+[%- endfor %]
+[%- endmacro %]
+
+[[dump_interfaces(toplevel_interfaces)]]
@@ -1,3 +1,6 @@
+{% assign pagename = page.url | replace_first: '/', '' | replace: '.html', '' %}
+{% if pagename == '' %}{% assign pagename = 'getting-started' %}{% endif %}
+
 <!DOCTYPE html>
 <!-- source: https://github.com/pages-themes/minimal/blob/master/_layouts/default.html -->
 <html lang="{{ site.lang | default: "en-US" }}">
@@ -23,20 +26,29 @@
          {% endif %}

          <p>{{ site.description | default: site.github.project_tagline }}</p>
-
+        </div>
+        <div style="overflow-y: auto;">
          <ul id="navbar">
            {% for section in site.data.index.sections %}
-            <li>
-              <p>{{ section.title }}</p>
+            <li class="navgroup">
+              <p class="navheader">{{ section.title }}</p>
              <ul>
+                {% if section.title != "API Reference" %}
                {% for item in section.docs %}
-                <li><a href="{{ item.url }}" alt="{{ item.title }}">{{ item.title }}</a></li>
+                {% assign prefix = item.url | slice: 0 %}
+                {% assign itemname = item.url | replace_first: '/', '' | replace: '.html', '' %}
+                {% if itemname == '' %}{% assign itemname = 'getting-started' %}{% endif %}
+                <li><a class="navitem{% if pagename == itemname %} currentitem{% endif %}" href="{% if prefix == '/' %}{{ site.baseurl }}{% endif %}{{ item.url }}" alt="{{ item.title }}">{{ item.title }}</a></li>
                {% endfor %}
+                {% else %}
+                {% include apiindex.html %}
+                {% endif %}
              </ul>
            </li>
            {% endfor %}
          </ul>
-
+        </div>
+        <div style="margin-top: 10px;">
          {% if site.github.is_project_page %}
          <p class="view"><a href="{{ site.github.repository_url }}">View the Project on GitHub <small>{{ site.github.repository_nwo }}</small></a></p>
          {% endif %}
@@ -59,15 +71,30 @@
      </header>
      <section>

-      <div class="edit">
-          {% assign filename = page.url | replace_first: '/', '' | replace: '.html', '.md' %}
-          {% if filename == '' %}{% assign filename = 'getting-started.md' %}{% endif %}
-        <!-- edit icon taken from GitHub -->
-        <svg transform="translate(0,1)" class="octicon octicon-pencil" viewBox="0 0 14 16" version="1.1" width="10" height="12" aria-hidden="true">
-          <path fill-rule="evenodd" d="M0 12v3h3l8-8-3-3-8 8zm3 2H1v-2h1v1h1v1zm10.3-9.3L12 6 9 3l1.3-1.3a.996.996 0 0 1 1.41 0l1.59 1.59c.39.39.39 1.02 0 1.41z"></path>
-        </svg>
-        <a href="https://www.github.com/madcowswe/ODrive/edit/master/docs/{{ filename }}">edit on GitHub</a>
-      </div>
+        <div class="pageactions">
+          <div>
+            <!-- edit icon taken from GitHub -->
+            <svg transform="translate(0,1)" class="octicon octicon-pencil" viewBox="0 0 14 16" version="1.1" width="10" height="12" aria-hidden="true">
+              <path fill-rule="evenodd" d="M0 12v3h3l8-8-3-3-8 8zm3 2H1v-2h1v1h1v1zm10.3-9.3L12 6 9 3l1.3-1.3a.996.996 0 0 1 1.41 0l1.59 1.59c.39.39.39 1.02 0 1.41z"></path>
+            </svg>
+            {% if page.edit_url %}
+            {% assign edit_url = "https://www.github.com/madcowswe/ODrive/edit/master/" | append: edit_url %}
+            {% else %}
+            {% assign edit_url = "https://www.github.com/madcowswe/ODrive/edit/master/docs/" | append: pagename | append: ".md" %}
+            {% endif %}
+            <a href="{{edit_url}}">edit on GitHub</a>
+          </div>
+
+          {% if page.download %}
+          <div>
+            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="10" height="10" style="fill: #656565;">
+              <path d="M216 0h80c13.3 0 24 10.7 24 24v168h87.7c17.8 0 26.7 21.5 14.1 34.1L269.7 378.3c-7.5 7.5-19.8 7.5-27.3 0L90.1 226.1c-12.6-12.6-3.7-34.1 14.1-34.1H192V24c0-13.3 10.7-24 24-24zm296 376v112c0 13.3-10.7 24-24 24H24c-13.3 0-24-10.7-24-24V376c0-13.3 10.7-24 24-24h146.7l49 49c20.1 20.1 52.5 20.1 72.6 0l49-49H488c13.3 0 24 10.7 24 24zm-124 88c0-11-9-20-20-20s-20 9-20 20 9 20 20 20 20-9 20-20zm64 0c0-11-9-20-20-20s-20 9-20 20 9 20 20 20 20-9 20-20z"/>
+            </svg>
+            <a href="https://www.github.com/madcowswe/ODrive/edit/master/{{page.download.url}}">{{page.download.text}}</a>
+          </div>
+          {% endif %}
+        </div>
+

      {{ content }}

@@ -105,6 +132,11 @@
        }
      }
    </script>
+    <script>
+      // Scroll the navbar to the position of the selected item
+      var element = document.getElementsByClassName("currentitem")[0];
+      element.scrollIntoView(false);
+    </script>
  </body>
 </html>

@@ -100,7 +100,7 @@ table {
  width:100%;
  border-collapse:collapse;
  display: block;
-  overflow-x: scroll;
+  overflow-x: auto;
 }

 th, td {
@@ -128,10 +128,12 @@ header {
  float:left;
  position:fixed;
  -webkit-font-smoothing:subpixel-antialiased;
-  
-  overflow-y: auto;
-  top: 50px;
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  top: 0;
  bottom: 0;
+  padding: 10px 0;
 }


@@ -261,7 +263,11 @@ a {
 }

 h1 a {
-    color: unset;
+  color: unset;
+}
+
+.navitem a {
+  color: unset;
 }

 // a:hover, a:focus {
@@ -270,6 +276,7 @@ h1 a {
 // }

 /*** Navigation bar ***/
+
 header > div {
  margin-right: 20px;
 }
@@ -287,42 +294,57 @@ header li {

 #navbar {
  max-width: 250px;
+  flex: 1;
+  overflow: auto;
+  margin: 0;
 }

-header ul p {
-    margin:0;
+.navgroup {
+  background: #9c9c9c;
+  margin-top: 20px;
+}
+.navgroup:first-child {
+  margin-top: 0px;
+}
+
+#navbar ul {
+  background-color: #ffffffa6;
+  margin: 0;
+}
+
+.navheader {
+    margin:0px;
    padding-left:5px;
    display: block;
 //     color: #d60000;
    color: #000;
    font-weight: bold;
-    background-color: #cbcbcb;
 }

-header ul ul li a {
-  background: #f8f8f8;
+.navitem {
  //border:1px solid #e0e0e0;
-  line-height:1;
  font-size:12px;
  font-weight: bold;
  color:#676767;
  display:block;
  text-align:left;
-  padding:12px 0px 5px 5px;
-  //margin:12px;
-  height:20px;
+  padding:0px 5px;
+  margin:0px;
+  height:37px;
+  line-height:37px;
 }

-//// rounded edges (look bad)
-//header ul p {
-//  border-radius:5px 5px 0 0;
-//}
-//header ul ul li:last-child a {
-//  border-radius:0 0 5px 5px;
-//}
+.navitem a { display: block; }
+
+.currentitem {
+  //-webkit-box-shadow: inset 0px 0px 5px 3px #aa0000a6;
+  //-moz-box-shadow: inset 0px 0px 5px 3px #aa0000a6;
+  //box-shadow: inset 0px 0px 5px 3px #aa0000a6;
+  color: #d60000;
+}

 /*** Navbar Hover ***/
-header ul a:hover, header ul a:focus {
+.navitem:hover, .navitem:focus {
  color: #d60000;
 //   color:rgb(0, 0, 0);
 //   background-color: rgba(0, 0, 0, 0.24);
@@ -418,11 +440,14 @@ details > div > p:last-child {
    border-left-color: #5bc0de;
 }

-/*** edit link ***/
-.edit {
+/*** edit/download link ***/
+.pageactions {
  float: right;
  font-size: 12px;
 }
+.pageactions > div {
+  text-align: right;
+}

 /*** inline code ***/
 :not(pre) > code {
@@ -441,3 +466,38 @@ table th {
 table tr:nth-child(2n) {
  background-color: #f8f8f8;
 }
+
+
+.expandable-list {
+  height: 100%;
+  margin: 0px;
+  //background-color: #ffbfbf61;
+  max-height: 0;
+  overflow: hidden;
+  -webkit-transition: max-height .5s ease-in-out;
+  transition: max-height .5s ease-in-out;
+}
+
+#navbar input[type=checkbox]:checked ~ .expandable-list { /* reset the height when checkbox is checked */
+  max-height: 1000px;
+}
+
+.chevron:before {
+  text-align: left;
+  content: "\3009"
+}
+
+.chevron {
+  float: left;
+  -webkit-transition: -webkit-transform .5s ease;
+  transition: transform .5s ease;
+  transform-origin: 40% 50%;
+  padding-left: 5px;
+  padding-right: 5px;
+}
+  
+#navbar input[type=checkbox]:checked ~ p .chevron { /* rotate down when checkbox is checked */
+  -webkit-transform: rotate(90deg);
+  -ms-transform: rotate(90deg);
+  transform: rotate(90deg);
+}
@@ -258,9 +258,14 @@ To run the docs server locally:

 ```bash
 cd docs
-gem install bundler
-bundle install --path ruby-bundle
-bundle exec jekyll serve --host=0.0.0.0
+gem install bundler # The gem command typically comes with a Ruby installation
+#export PATH="$PATH:~/.gem/ruby/2.7.0/bin" # or similar (depends on OS)
+rm Gemfile.lock # only if below commands cause trouble
+bundle config path ruby-bundle
+bundle install
+mkdir -p _api _includes
+python ../Firmware/interface_generator_stub.py --definitions ../Firmware/odrive-interface.yaml --template _layouts/api_documentation_template.j2 --outputs _api/'#'.md && python ../Firmware/interface_generator_stub.py --definitions ../Firmware/odrive-interface.yaml --template _layouts/api_index_template.j2 --output _includes/apiindex.html
+bundle exec jekyll serve --incremental --host=0.0.0.0
 ```

 ## Releases