Merge pull request #697 from ru-fu/LXD-298-distrobuilder-docs

Distrobuilder docs

.github/workflows/docbuild.yml

@@ -0,0 +1,25 @@
+name: Build documentation
+on:
+  - push
+  - pull_request
+
+jobs:
+  doc:
+    name: Build Sphinx documentation
+    runs-on: ubuntu-20.04
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Build docs
+        run: make doc
+
+      - name: Print warnings
+        run: if [ -s .sphinx/warnings.txt ]; then cat .sphinx/warnings.txt; exit 1; fi
+
+      - name: Upload artifacts
+        if: always()
+        uses: actions/upload-artifact@v3
+        with:
+          name: documentation
+          path: doc/html

.github/workflows/doctest.yml

@@ -0,0 +1,61 @@
+name: Documentation checks
+
+on:
+  - push
+  - pull_request
+
+jobs:
+  woke:
+    name: woke
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: woke
+        uses: get-woke/woke-action@v0
+        with:
+          # Cause the check to fail on any broke rules
+          fail-on-error: true
+          woke-args: "*.md **/*.md -c https://github.com/canonical-web-and-design/Inclusive-naming/raw/main/config.yml"
+
+  spellcheck:
+    name: Spelling check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Install Aspell
+        run: |
+          sudo apt-get install aspell aspell-en
+
+      - name: Build docs and run spelling checker
+        run: |
+          make doc-spellcheck
+
+  linkcheck:
+    name: Check links
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Run linkchecker
+        run: |
+          make doc-linkcheck
+
+  markdownlint:
+    name: Markdownlint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Install mdl
+        run: |
+          sudo snap install mdl
+
+      - name: Run mdl
+        run: |
+          make doc-lint

.gitignore

@@ -0,0 +1,8 @@
+# Sphinx
+doc/html/
+.sphinx/deps/
+.sphinx/themes/
+.sphinx/venv/
+.sphinx/warnings.txt
+.sphinx/.wordlist.dic
+.sphinx/_static/download

.sphinx/.markdownlint/doc-lint.sh

@@ -0,0 +1,34 @@
+#!/bin/sh -eu
+
+if ! command -v mdl >/dev/null; then
+    echo "Install mdl with 'snap install mdl' first."
+    exit 1
+fi
+
+trap "rm -rf .tmp/" EXIT
+
+## Preprocessing
+
+for fn in $(find doc/ -name '*.md'); do
+    mkdir -p $(dirname ".tmp/$fn");
+    sed -E "s/(\(.+\)=)/\1\n/" $fn > .tmp/$fn;
+done
+
+mdl .tmp/doc -s.sphinx/.markdownlint/style.rb -u.sphinx/.markdownlint/rules.rb --ignore-front-matter > .tmp/errors.txt || true
+
+if [ ! -s ".tmp/errors.txt" ]; then
+    echo "Passed!"
+    exit 0
+fi
+
+## Postprocessing
+
+filtered_errors="$(grep -vxFf .sphinx/.markdownlint/exceptions.txt .tmp/errors.txt)"
+if [ "$(echo "$filtered_errors" | wc -l)" = "2" ]; then
+    echo "Passed!"
+    exit 0
+else
+    echo "Failed!"
+    echo "$filtered_errors"
+    exit 1
+fi

.sphinx/.markdownlint/rules.rb

@@ -0,0 +1,44 @@
+rule 'Myst-MD031', 'Fenced code blocks should be surrounded by blank lines' do
+  tags :code, :blank_lines
+  aliases 'blanks-around-fences'
+  check do |doc|
+    errors = []
+    # Some parsers (including kramdown) have trouble detecting fenced code
+    # blocks without surrounding whitespace, so examine the lines directly.
+    in_code = false
+    fence = nil
+    lines = [''] + doc.lines + ['']
+    lines.each_with_index do |line, linenum|
+      line.strip.match(/^(`{3,}|~{3,})/)
+      unless Regexp.last_match(1) &&
+             (
+               !in_code ||
+               (Regexp.last_match(1).slice(0, fence.length) == fence)
+             )
+        next
+      end
+
+      fence = in_code ? nil : Regexp.last_match(1)
+      in_code = !in_code
+      if (in_code && !(lines[linenum - 1].empty? || lines[linenum - 1].match(/^[:\-\*]*\s*\% /))) ||
+         (!in_code && !(lines[linenum + 1].empty? || lines[linenum + 1].match(/^\s*:/)))
+        errors << linenum
+      end
+    end
+    errors
+  end
+end
+
+
+rule 'Myst-IDs', 'MyST IDs should be preceded by a blank line' do
+  check do |doc|
+    errors = []
+    ids = doc.matching_text_element_lines(/^\(.+\)=\s*$/)
+    ids.each do |linenum|
+      if (linenum > 1) && !doc.lines[linenum - 2].empty?
+        errors << linenum
+      end
+    end
+    errors.sort
+  end
+end

.sphinx/.markdownlint/style.rb

@@ -0,0 +1,12 @@
+all
+exclude_rule 'MD013'
+exclude_rule 'MD046'
+exclude_rule 'MD041'
+exclude_rule 'MD040'
+exclude_rule 'MD024'
+exclude_rule 'MD033'
+exclude_rule 'MD022'
+exclude_rule 'MD031'
+rule 'MD026', :punctuation => '.,;:!'
+rule 'MD003', :style => :atx
+rule 'MD007', :indent => 3

.sphinx/.spellcheck.yaml

@@ -0,0 +1,24 @@
+matrix:
+- name: Markdown files
+  aspell:
+    lang: en
+    d: en_US
+  dictionary:
+    wordlists:
+    - .sphinx/wordlist.txt
+    output: .sphinx/.wordlist.dic
+  sources:
+  - doc/html/**/*.html
+  pipeline:
+  - pyspelling.filters.html:
+      comments: false
+      attributes:
+      - title
+      - alt
+      ignores:
+      - code
+      - pre
+      - spellexception
+      - link
+      - title
+      - div.relatedlinks

.sphinx/_extra/versions.json

@@ -0,0 +1,6 @@
+[
+    {
+        "version": "latest",
+        "id": "latest"
+    }
+]

.sphinx/_static/custom.css

@@ -0,0 +1,170 @@
+/** Fix the font weight (300 for normal, 400 for slightly bold) **/
+
+div.page, h1, h2, h3, h4, h5, h6, .sidebar-tree .current-page>.reference, button, input, optgroup, select, textarea, th.head {
+    font-weight: 300
+}
+
+.toc-tree li.scroll-current>.reference, dl.glossary dt, dl.simple dt, dl:not([class]) dt {
+    font-weight: 400;
+}
+
+/** Table styling **/
+
+th.head {
+    text-transform: uppercase;
+    font-size: var(--font-size--small);
+}
+
+table.docutils {
+    border: 0;
+    box-shadow: none;
+    width:100%;
+}
+
+table.docutils td, table.docutils th, table.docutils td:last-child, table.docutils th:last-child, table.docutils td:first-child, table.docutils th:first-child {
+    border-right: none;
+    border-left: none;
+}
+
+/* center align table cells with ":-:" */
+td.text-center {
+    text-align: center;
+}
+
+/** No rounded corners **/
+
+.admonition, code.literal, .sphinx-tabs-tab, .sphinx-tabs-panel, .highlight {
+    border-radius: 0;
+}
+
+/** Admonition styling **/
+
+.admonition {
+    border-top: 1px solid #d9d9d9;
+    border-right: 1px solid #d9d9d9;
+    border-bottom: 1px solid #d9d9d9;
+}
+
+/** Color for the "copy link" symbol next to headings **/
+
+a.headerlink {
+    color: var(--color-brand-primary);
+}
+
+/** Line to the left of the current navigation entry **/
+
+.sidebar-tree li.current-page {
+    border-left: 2px solid var(--color-brand-primary);
+}
+
+/** Some tweaks for issue #16 **/
+
+[role="tablist"] {
+    border-bottom: 1px solid var(--color-sidebar-item-background--hover);
+}
+
+.sphinx-tabs-tab[aria-selected="true"] {
+    border: 0;
+    border-bottom: 2px solid var(--color-brand-primary);
+    background-color: var(--color-sidebar-item-background--current);
+    font-weight:300;
+}
+
+.sphinx-tabs-tab{
+    color: var(--color-brand-primary);
+    font-weight:300;
+}
+
+.sphinx-tabs-panel {
+    border: 0;
+    border-bottom: 1px solid var(--color-sidebar-item-background--hover);
+    background: var(--color-background-primary);
+}
+
+button.sphinx-tabs-tab:hover {
+    background-color: var(--color-sidebar-item-background--hover);
+}
+
+/** Custom classes to fix scrolling in tables by decreasing the
+    font size or breaking certain columns.
+    Specify the classes in the Markdown file with, for example:
+    ```{rst-class} break-col-4 min-width-4-8
+    ```
+**/
+
+table.dec-font-size {
+    font-size: smaller;
+}
+table.break-col-1 td.text-left:first-child {
+    word-break: break-word;
+}
+table.break-col-4 td.text-left:nth-child(4) {
+    word-break: break-word;
+}
+table.min-width-1-15 td.text-left:first-child {
+    min-width: 15em;
+}
+table.min-width-4-8 td.text-left:nth-child(4) {
+    min-width: 8em;
+}
+
+/** Underline for abbreviations **/
+
+abbr[title] {
+    text-decoration: underline solid #cdcdcd;
+}
+
+/** Use the same style for right-details as for left-details **/
+.bottom-of-page .right-details {
+    font-size: var(--font-size--small);
+    display: block;
+}
+
+/** Version switcher */
+button.version_select {
+  color: var(--color-foreground-primary);
+  background-color: var(--color-toc-background);
+  padding: 5px 10px;
+  border: none;
+}
+
+.version_select:hover, .version_select:focus {
+    background-color: var(--color-sidebar-item-background--hover);
+}
+
+.version_dropdown {
+  position: relative;
+  display: inline-block;
+  text-align: right;
+  font-size: var(--sidebar-item-font-size);
+}
+
+.available_versions {
+  display: none;
+  position: absolute;
+  right: 0px;
+  background-color: var(--color-toc-background);
+  box-shadow: 0px 8px 16px 0px rgba(0,0,0,0.2);
+  z-index: 11;
+}
+
+.available_versions a {
+  color: var(--color-foreground-primary);
+  padding: 12px 16px;
+  text-decoration: none;
+  display: block;
+}
+
+.available_versions a:hover {background-color: var(--color-sidebar-item-background--current)}
+
+.show {display:block;}
+
+/** Fix for nested numbered list - the nested list is lettered **/
+ol.arabic ol.arabic {
+  list-style: lower-alpha;
+}
+
+/** Make expandable sections look like links **/
+details summary {
+    color: var(--color-link);
+}