Update Documentation

- added screenshot - added doc export using pandoc to html and pdf
2025-12-21 17:33:03 +01:00
parent 576d3a55ad
commit 423de19775
9 changed files with 27707 additions and 1 deletions
--- a/.gitattributes
+++ b/.gitattributes
@@ -0,0 +1,2 @@
+*.pdf filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
--- a/README.MD
+++ b/README.MD
@@ -1,15 +1,30 @@
+---
+title: "QLC Plus configuration"
+toc-own-page: true
+titlepage: true
+...
+
+## Links to the Documentation {.noexport}
+[PDF Version](doc/build/Documentation.pdf)
+
+[HTML Version](http://htmlpreview.github.io/?https://raw.githubusercontent.com/dustinbrun/QLC_Plus_configuration/refs/heads/main/doc/build/index.html)
+
+
 # QLC Plus configuration

 This repository contains all files needed to setup the lighting console using [Q Light Controller +](https://www.qlcplus.org/).

 Tested with QLC+ Version 4.12.7 ([download](https://www.qlcplus.org/downloads/4.12.7/QLC+_4.12.7-1.exe))

+![](pictures/screenshot.png)
+
 ## Setup
 Before opening the preset, import the fixtures first. See [`user_folder_QLC+`](user_folder_QLC+/README.MD) for details.


+## Advanced Information

-## Device patch
+### Device patch

 start address  | range      | end address   | name                          | type                      
 -------------  | ---------  | ------------  | -----------------             | -----------------------
@@ -27,3 +42,11 @@ start address  | range      | end address   | name                          | ty
 ~~100~~        | ~~10~~     | ~~110~~       | ~~Moving Head 1~~             | ~~n.a.~~
 111            | 11         | 121           | MH2 FG PicoSpot 20            | Fun Generation PicoSpot 20 LED
 122            | 11         | 132           | MH3 FG PicoSpot 20            | Fun Generation PicoSpot 20 LED
+
+
+### Concept of operation
+
+...
+
+> [!NOTE]  
+> TODO: Describe Concept of operation
--- a/doc/build/Documentation.pdf
+++ b/doc/build/Documentation.pdf
--- a/doc/build/index.html
+++ b/doc/build/index.html
--- a/doc/tools/bootstrap_menu.html
+++ b/doc/tools/bootstrap_menu.html
@@ -0,0 +1,123 @@
+<!doctype html>
+<html $if(lang)$ lang="$lang$" $endif$>
+<head>
+    
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <!--[if lt IE 9]>
+                <script src="http://css3-mediaqueries-js.googlecode.com/svn/trunk/css3-mediaqueries.js"></script>
+        <![endif]-->
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <meta http-equiv="Content-Style-Type" content="text/css" />
+
+    <!-- <link rel="stylesheet" type="text/css" href="template.css" /> -->
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/gh/diversen/pandoc-bootstrap-adaptive-template@959c3622/template.css" />
+
+    <link href="https://vjs.zencdn.net/5.4.4/video-js.css" rel="stylesheet" />
+
+    <script src="https://code.jquery.com/jquery-2.2.1.min.js"></script>
+    <!-- <script type='text/javascript' src='menu/js/jquery.cookie.js'></script> -->
+    <!-- <script type='text/javascript' src='menu/js/jquery.hoverIntent.minified.js'></script> -->
+    <!-- <script type='text/javascript' src='menu/js/jquery.dcjqaccordion.2.7.min.js'></script> -->
+
+    <!-- <link href="menu/css/skins/blue.css" rel="stylesheet" type="text/css" /> -->
+    <!-- <link href="menu/css/skins/graphite.css" rel="stylesheet" type="text/css" /> -->
+    <!-- <link href="menu/css/skins/grey.css" rel="stylesheet" type="text/css" /> -->
+  
+    <!-- <script src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script> -->
+        
+  
+    <!-- <script src="script.js"></script> -->
+  
+    <!-- <script src="jquery.sticky-kit.js "></script> -->
+    <script type='text/javascript' src='https://cdn.jsdelivr.net/gh/diversen/pandoc-bootstrap-adaptive-template@959c3622/menu/js/jquery.cookie.js'></script>
+    <script type='text/javascript' src='https://cdn.jsdelivr.net/gh/diversen/pandoc-bootstrap-adaptive-template@959c3622/menu/js/jquery.hoverIntent.minified.js'></script>
+    <script type='text/javascript' src='https://cdn.jsdelivr.net/gh/diversen/pandoc-bootstrap-adaptive-template@959c3622/menu/js/jquery.dcjqaccordion.2.7.min.js'></script>
+
+    <link href="https://cdn.jsdelivr.net/gh/diversen/pandoc-bootstrap-adaptive-template@959c3622/menu/css/skins/blue.css" rel="stylesheet" type="text/css" />
+    <link href="https://cdn.jsdelivr.net/gh/diversen/pandoc-bootstrap-adaptive-template@959c3622/menu/css/skins/graphite.css" rel="stylesheet" type="text/css" />
+    <link href="https://cdn.jsdelivr.net/gh/diversen/pandoc-bootstrap-adaptive-template@959c3622/menu/css/skins/grey.css" rel="stylesheet" type="text/css" />
+  
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.4/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+  
+    <script src="https://cdn.jsdelivr.net/gh/diversen/pandoc-bootstrap-adaptive-template@959c3622/script.js"></script>
+  
+    <script src="https://cdn.jsdelivr.net/gh/diversen/pandoc-bootstrap-adaptive-template@959c3622/jquery.sticky-kit.js"></script>
+    <meta name="generator" content="pandoc" />
+$for(author-meta)$
+  <meta name="author" content="$author-meta$" />
+$endfor$
+$if(date-meta)$
+  <meta name="date" content="$date-meta$" />
+$endif$
+  <title>$if(title-prefix)$$title-prefix$ - $endif$$pagetitle$</title>
+  <style type="text/css">code{white-space: pre;}</style>
+$if(quotes)$
+  <style type="text/css">q { quotes: "“" "”" "‘" "’"; }</style>
+$endif$
+$if(highlighting-css)$
+  <style type="text/css">
+$highlighting-css$
+  </style>
+$endif$
+$for(css)$
+  <link rel="stylesheet" href="$css$" $if(html5)$$else$type="text/css" $endif$/>
+$endfor$
+$if(math)$
+  $math$
+$endif$
+$for(header-includes)$
+  $header-includes$
+$endfor$
+</head>
+<body>
+
+    
+  $if(title)$
+  <div class="navbar navbar-static-top">
+    <div class="navbar-inner">
+      <div class="container">
+        <span class="doc-title">$title$</span>
+        <ul class="nav pull-right doc-info">
+          $for(author)$
+          <li><p class="navbar-text">$author$</p></li>
+          $endfor$
+          $if(date)$
+          <li><p class="navbar-text">$date$</p></li>
+          $endif$
+        </ul>
+      </div>
+    </div>
+  </div>
+  $endif$
+  <div class="container">
+    <div class="row">
+      $if(toc)$
+      <div id="$idprefix$TOC" class="span3">
+        <div class="well toc">
+
+        $toc$
+
+        </div>
+      </div>
+      $endif$
+      <div class="span$if(toc)$9$else$12$endif$">
+
+      $if(abstract)$
+          <H1>$abstract-title$</H1>
+          $abstract$
+      $endif$
+
+      $for(include-before)$
+      $include-before$
+      $endfor$
+$body$
+      $for(include-after)$
+      $include-after$
+      $endfor$
+      </div>
+    </div>
+  </div>
+  <script src="https://vjs.zencdn.net/5.4.4/video.js"></script>
+
+</body>
+</html>
--- a/doc/tools/eisvogel.latex
+++ b/doc/tools/eisvogel.latex
--- a/doc/tools/noexport-subtrees.lua
+++ b/doc/tools/noexport-subtrees.lua
@@ -0,0 +1,61 @@
+--[[
+Remove all subtrees whose headlines contain class `noexport`.
+
+License:   MIT
+Copyright: © Albert Krewinkel
+]]
+
+-- pandoc.utils.make_sections exists since pandoc 2.8
+PANDOC_VERSION:must_be_at_least {2,8}
+
+local utils = require 'pandoc.utils'
+
+-- Returns true iff a div is a section div.
+local function is_section_div (div)
+  return div.t == 'Div'
+    and div.classes[1] == 'section'
+    and div.attributes.number
+end
+
+-- Returns the header element of a section, or nil if the argument is not a
+-- section.
+local function section_header (div)
+  if not div.t == 'Div' then return nil end
+  local header = div.content and div.content[1]
+  local is_header = is_section_div(div)
+    and header
+    and header.t == 'Header'
+  return is_header and header or nil
+end
+
+--- Remove remaining section divs
+local function flatten_sections (div)
+  local header = section_header(div)
+  if not header then
+    return nil
+  else
+    header.identifier = div.identifier
+    div.content[1] = header
+    return div.content
+  end
+end
+
+function drop_noexport_sections (div)
+  if div.classes:includes('noexport') then
+    return {}
+  end
+end
+
+--- Setup the document for further processing by wrapping all
+--- sections in Div elements.
+function setup_document (doc)
+  local sections = utils.make_sections(false, nil, doc.blocks)
+  return pandoc.Pandoc(sections, doc.meta)
+end
+
+return {
+  {Pandoc = setup_document},
+  {Div = drop_noexport_sections},
+  {Div = flatten_sections}
+}
+
--- a/make_doc.bat
+++ b/make_doc.bat
@@ -0,0 +1,31 @@
+@echo off
+setlocal enabledelayedexpansion
+
+REM Check dependencies
+where pandoc >nul 2>&1
+if errorlevel 1 (
+    echo ERROR: Pandoc not found in PATH.
+    exit /b 1
+)
+
+echo Generating PDF ...
+pandoc README.md ^
+    --lua-filter="./doc/tools/noexport-subtrees.lua" ^
+    --template="./doc/tools/eisvogel.latex" ^
+    --toc ^
+    --number-sections ^
+    --pdf-engine=xelatex ^
+    -o "./doc/build/Documentation.pdf"
+
+echo Generating HTML ...
+pandoc README.md ^
+    --lua-filter="./doc/tools/noexport-subtrees.lua" ^
+    --template="./doc/tools/bootstrap_menu.html" ^
+    --toc ^
+    --toc-depth=6 ^
+    --standalone ^
+    --embed-resources ^
+    -o "./doc/build/index.html"
+
+echo Done.
+
--- a/pictures/screenshot.png
+++ b/pictures/screenshot.png