Initial work on manual auto-generation.

.github/workflows/render_user_manual.yml

@@ -0,0 +1,33 @@
+name: Render User Manual
+
+on:
+  push
+
+jobs:
+  build:
+    # The CMake configure and build commands are platform agnostic and should work equally
+    # well on Windows or Mac.  You can convert this to a matrix build if you need
+    # cross-platform coverage.
+    # See: https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions/managing-complex-workflows#using-a-build-matrix
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Install packages
+      shell: bash
+      run: sudo apt-get install texlive texlive-latex-extra texlive-fonts-extra texlive-lang-german texlive-lang-english lmodern latex-xcolor
+
+    # Note: this is adapted from https://github.com/LibreSolar/md-manual-template/blob/master/.travis.yml
+    - name: Generate manual
+      shell: bash
+      run: |
+          pandoc_version=`wget -O - --max-redirect 0 https://github.com/jgm/pandoc/releases/latest 2>&1 | grep "Location:" | sed 's/.*\/tag\/\([^ "]*\).*/\1/'`
+          pandoc_deb="pandoc-${pandoc_version}-1-amd64.deb"
+          wget "https://github.com/jgm/pandoc/releases/download/${pandoc_version}/${pandoc_deb}"
+          sudo dpkg -i ${pandoc_deb}
+          rm ${pandoc_deb}
+          pandoc -v
+          cd manual
+          make dist
+        

manual/1-introduction.md

@@ -0,0 +1,7 @@
+# Introduction
+
+This document gives an example of how the Markdown Manual Template can be used.
+
+The template expects normal makdown (with pandoc extensions) as an input and generates a nice static HTML 5 website and a PDF document.
+
+![The Creative Commons Attribution-ShareAlike logo](images/cc-by-sa.png)

manual/2-usage.md

@@ -0,0 +1,29 @@
+# Usage
+
+## Folder structure
+
+Everything you need is stored in the `manual` subfolder. This makes sure it is easy to integrate into existing projects. Just copy the folder from this example to your own repository.
+
+## Pandoc metadata
+
+Some advanced configuration for pandoc is stored in the file `metadata.txt`.
+
+## Markdown input
+
+The markdown file names should be numbered according to the order in the final document. Header numbers are generated automatically by pandoc and should not be added in the markdown files.
+
+## HTML generation
+
+The HTML template is based on the great [mdBook](https://github.com/rust-lang-nursery/mdBook) theme, which was simplified and adjusted a bit to suit the needs of a manual.
+
+In the `manual` subfolder call:
+
+   pandoc metadata.txt *.md -o manual.html --template template/mdbook.html --from markdown --listings --number-sections --toc --toc-depth=2 --katex
+
+## PDF generation
+
+PDF files are generated using LaTeX, so a working LaTeX engine needs to be installed on your system already (e.g. texlive). The manual uses the [Eisvogel](https://github.com/Wandmalfarbe/pandoc-latex-template) template.
+
+In the `manual` subfolder call:
+
+   pandoc metadata.txt *.md -o manual.pdf --template template/eisvogel.tex --from markdown --listings --number-sections --toc

manual/3-math.md

@@ -0,0 +1,11 @@
+# Math rendering support
+
+Pandoc supports math rendering in HTML using different engines. We recommend to use the [KaTeX](https://katex.org/) engine, specified by the `--katex` option on the command-line.
+
+In-line math equations like $U = R \cdot I$ must be wrapped within two `$`-signs, without a space after the starting `$` and without a space before the ending `$`.
+
+Math equations in a separate line are defined using two `$$`. They are rendered like this:
+
+$$\rho\dot{\vec{v}}
+=\rho\left(\frac{\partial\vec{v}}{\partial t}+(\vec{v}\cdot\nabla)\vec{v}\right)
+=-\nabla p+\mu\Delta\vec{v}+(\lambda+\mu)\nabla (\nabla\cdot\vec{v})+\vec{f}.$$

manual/4-code.md

@@ -0,0 +1,11 @@
+# Code highlighting
+
+Here is an example of highlighted C++ code:
+
+```C++
+int main()
+{
+    printf("Time: %d\n", time(NULL));
+}
+
+```

manual/Makefile

@@ -0,0 +1,2 @@
+export TOOL_DIR = tool
+include $(TOOL_DIR)/Makefile_include

manual/metadata.yml

@@ -0,0 +1,17 @@
+---
+title: "Template Device"
+title-prefix: "User Manual"
+subtitle: "User Manual"
+author: [Mooneer Salem]
+date: "2024-03-15"
+subject: "Markdown"
+keywords: [Markdown, Example]
+lang: "en"
+titlepage: true
+titlepage-text-color: "005e85"
+titlepage-rule-color: "005e85"
+titlepage-rule-height: 2
+logo: "images/libresolar-logo-lateral.pdf"
+logo-width: 200
+toc-own-page: true
+...

manual/tool/Makefile_include

@@ -0,0 +1,46 @@
+# NOTE This variable has to bedefined in the including file:
+#TOOL_DIR = tool
+
+OUT_DIR = build
+RESOURCES = $(TOOL_DIR)/template images
+MKDIR_P = mkdir -p
+
+# Targets not producing a file with their name
+.PHONY: all pdf html dist clean
+
+all:: pdf html
+
+pdf:: metadata.yml *.md
+	pandoc \
+		metadata.yml *.md \
+		--output manual.pdf \
+		--template $(TOOL_DIR)/template/eisvogel.tex \
+		--from markdown \
+		--listings \
+		--number-sections \
+		--table-of-contents \
+		--metadata date="`date -u '+%Y-%m-%d'`"
+
+html:: metadata.yml *.md
+	pandoc \
+		metadata.yml *.md \
+		--output manual.html \
+		--template $(TOOL_DIR)/template/mdbook.html \
+		--from markdown \
+		--listings \
+		--number-sections \
+		--table-of-contents \
+		--toc-depth=2 \
+		--katex \
+		--metadata date="`date -u '+%Y-%m-%d'`"
+
+dist:: all
+	${MKDIR_P} ${OUT_DIR}
+	cp -r ${RESOURCES} ${OUT_DIR}/
+	mv manual.pdf ${OUT_DIR}/
+	mv manual.html ${OUT_DIR}/index.html
+
+clean::
+	rm -f manual.pdf
+	rm -f manual.html
+	rm -rf ${OUT_DIR}

manual/tool/template/book.js

@@ -0,0 +1,136 @@
+"use strict";
+
+// Fix back button cache problem
+window.onunload = function () { };
+
+(function sidebar() {
+    var html = document.querySelector("html");
+    var sidebar = document.getElementById("sidebar");
+    var sidebarLinks = document.querySelectorAll('#sidebar a');
+    var sidebarToggleButton = document.getElementById("sidebar-toggle");
+    var firstContact = null;
+
+    function showSidebar() {
+        html.classList.remove('sidebar-hidden')
+        html.classList.add('sidebar-visible');
+        Array.from(sidebarLinks).forEach(function (link) {
+            link.setAttribute('tabIndex', 0);
+        });
+        sidebarToggleButton.setAttribute('aria-expanded', true);
+        sidebar.setAttribute('aria-hidden', false);
+        try { localStorage.setItem('mdbook-sidebar', 'visible'); } catch (e) { }
+    }
+
+    function hideSidebar() {
+        html.classList.remove('sidebar-visible')
+        html.classList.add('sidebar-hidden');
+        Array.from(sidebarLinks).forEach(function (link) {
+            link.setAttribute('tabIndex', -1);
+        });
+        sidebarToggleButton.setAttribute('aria-expanded', false);
+        sidebar.setAttribute('aria-hidden', true);
+        try { localStorage.setItem('mdbook-sidebar', 'hidden'); } catch (e) { }
+    }
+
+    // Toggle sidebar
+    sidebarToggleButton.addEventListener('click', function sidebarToggle() {
+        if (html.classList.contains("sidebar-hidden")) {
+            showSidebar();
+        } else if (html.classList.contains("sidebar-visible")) {
+            hideSidebar();
+        } else {
+            if (getComputedStyle(sidebar)['transform'] === 'none') {
+                hideSidebar();
+            } else {
+                showSidebar();
+            }
+        }
+    });
+
+    document.addEventListener('touchstart', function (e) {
+        firstContact = {
+            x: e.touches[0].clientX,
+            time: Date.now()
+        };
+    }, { passive: true });
+
+    document.addEventListener('touchmove', function (e) {
+        if (!firstContact)
+            return;
+
+        var curX = e.touches[0].clientX;
+        var xDiff = curX - firstContact.x,
+            tDiff = Date.now() - firstContact.time;
+
+        if (tDiff < 250 && Math.abs(xDiff) >= 150) {
+            if (xDiff >= 0 && firstContact.x < Math.min(document.body.clientWidth * 0.25, 300))
+                showSidebar();
+            else if (xDiff < 0 && curX < 300)
+                hideSidebar();
+
+            firstContact = null;
+        }
+    }, { passive: true });
+
+    // Scroll sidebar to current active section
+    var activeSection = sidebar.querySelector(".active");
+    if (activeSection) {
+        sidebar.scrollTop = activeSection.offsetTop;
+    }
+})();
+
+(function chapterNavigation() {
+    document.addEventListener('keydown', function (e) {
+        if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) { return; }
+        if (window.search && window.search.hasFocus()) { return; }
+
+        switch (e.key) {
+            case 'ArrowRight':
+                e.preventDefault();
+                var nextButton = document.querySelector('.nav-chapters.next');
+                if (nextButton) {
+                    window.location.href = nextButton.href;
+                }
+                break;
+            case 'ArrowLeft':
+                e.preventDefault();
+                var previousButton = document.querySelector('.nav-chapters.previous');
+                if (previousButton) {
+                    window.location.href = previousButton.href;
+                }
+                break;
+        }
+    });
+})();
+
+(function scrollToTop () {
+    var menuTitle = document.querySelector('.menu-title');
+
+    menuTitle.addEventListener('click', function () {
+        document.scrollingElement.scrollTo({ top: 0, behavior: 'smooth' });
+    });
+})();
+
+(function autoHideMenu() {
+    var menu = document.getElementById('menu-bar');
+
+    var previousScrollTop = document.scrollingElement.scrollTop;
+
+    document.addEventListener('scroll', function () {
+        if (menu.classList.contains('folded') && document.scrollingElement.scrollTop < previousScrollTop) {
+            menu.classList.remove('folded');
+        } else if (!menu.classList.contains('folded') && document.scrollingElement.scrollTop > previousScrollTop) {
+            menu.classList.add('folded');
+        }
+
+        if (!menu.classList.contains('bordered') && document.scrollingElement.scrollTop > 0) {
+            menu.classList.add('bordered');
+        }
+
+        if (menu.classList.contains('bordered') && document.scrollingElement.scrollTop === 0) {
+            menu.classList.remove('bordered');
+        }
+
+        previousScrollTop = document.scrollingElement.scrollTop;
+    }, { passive: true });
+})();