Robert Krátký has proposed merging
~rkratky/ubuntu-governance-docs:update-starter-pack into
ubuntu-governance-docs:main.
Commit message:
Update the Docs Started Pack to latest version
Requested reviews:
Robie Basak (racb)
For more details, see:
https://code.launchpad.net/~rkratky/ubuntu-governance-docs/+git/ubuntu-governance-docs/+merge/482863
* Merge Makefiles
* Adapt templates and config for Launchpad
* Add new features (metrics, vale linting)
* Remove unused artifacts
* Various small enhancements
--
Your team Ubuntu Technical Board is subscribed to branch
ubuntu-governance-docs:main.
diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt
index e69de29..01abb2d 100644
--- a/docs/.custom_wordlist.txt
+++ b/docs/.custom_wordlist.txt
@@ -0,0 +1,24 @@
+# Leave a blank line at the end of this file to support concatenation
+cjk
+cryptographically
+dvipng
+fonts
+freefont
+github
+GPG
+gyre
+https
+lang
+latexmk
+otf
+plantuml
+tex
+texlive
+TOC
+utils
+WCAG
+xetex
+xindy
+kustom
+wordlist
+txt
diff --git a/docs/.gitignore b/docs/.gitignore
index da6f688..bf16e0d 100644
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -1,14 +1,25 @@
-/*env*/
+# Environment
+*env*/
.sphinx/venv/
+
+# Sphinx
.sphinx/warnings.txt
.sphinx/.wordlist.dic
.sphinx/.doctrees/
.sphinx/node_modules/
-package*.json
+
+# Vale
+.sphinx/styles/*
+.sphinx/vale.ini
+
+# Build outputs
_build
+
+# Node.js
+package*.json
+
+# Unrelated cache and config files
.DS_Store
__pycache__
.idea/
.vscode/
-.sphinx/styles/*
-.sphinx/vale.ini
\ No newline at end of file
diff --git a/docs/.sphinx/.markdownlint.json b/docs/.sphinx/.markdownlint.json
new file mode 100644
index 0000000..f42753f
--- /dev/null
+++ b/docs/.sphinx/.markdownlint.json
@@ -0,0 +1,27 @@
+{
+ "default": false,
+ "MD003": {
+ "style": "atx"
+ },
+ "MD013": {
+ "code_blocks": false,
+ "tables": false,
+ "stern": true,
+ "line_length": 150
+ },
+ "MD014": true,
+ "MD018": true,
+ "MD022": true,
+ "MD023": true,
+ "MD026": {
+ "punctuation": ".,;。，；"
+ },
+ "MD031": {
+ "list_items": false
+ },
+ "MD032": true,
+ "MD035": true,
+ "MD042": true,
+ "MD045": true,
+ "MD052": true
+}
\ No newline at end of file
diff --git a/docs/.sphinx/.pre-commit-config.yaml b/docs/.sphinx/.pre-commit-config.yaml
new file mode 100644
index 0000000..07e0b48
--- /dev/null
+++ b/docs/.sphinx/.pre-commit-config.yaml
@@ -0,0 +1,23 @@
+repos:
+ - repo: local
+ hooks:
+ - id: make-spelling
+ name: Run make spelling
+ entry: make -C docs spelling
+ language: system
+ pass_filenames: false
+ files: ^docs/.*\.(rst|md|txt)$
+
+ - id: make-linkcheck
+ name: Run make linkcheck
+ entry: make -C docs linkcheck
+ language: system
+ pass_filenames: false
+ files: ^docs/.*\.(rst|md|txt)$
+
+ - id: make-woke
+ name: Run make woke
+ entry: make -C docs woke
+ language: system
+ pass_filenames: false
+ files: ^docs/.*\.(rst|md|txt)$
diff --git a/docs/.sphinx/.wordlist.txt b/docs/.sphinx/.wordlist.txt
index fb4137d..be5021a 100644
--- a/docs/.sphinx/.wordlist.txt
+++ b/docs/.sphinx/.wordlist.txt
@@ -1,13 +1,15 @@
-# This wordlist is from the Sphinx starter pack and should not be
-# modified. Add any custom terms to .custom_wordlist.txt instead.
-
+ACME
+ACME's
addons
+AGPLv
API
APIs
balancer
Charmhub
CLI
+DCO
Diátaxis
+Dqlite
dropdown
EBS
EKS
@@ -53,6 +55,7 @@ RTD
subdirectories
subfolders
subtree
+TODO
Ubuntu
UI
UUID
diff --git a/docs/.sphinx/_static/favicon.png b/docs/.sphinx/_static/favicon.png
deleted file mode 100644
index 7f175e4..0000000
Binary files a/docs/.sphinx/_static/favicon.png and /dev/null differ
diff --git a/docs/.sphinx/_static/project_specific.css b/docs/.sphinx/_static/project_specific.css
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/docs/.sphinx/_static/project_specific.css
diff --git a/docs/.sphinx/_static/tag.png b/docs/.sphinx/_static/tag.png
deleted file mode 100644
index f6f6e5a..0000000
Binary files a/docs/.sphinx/_static/tag.png and /dev/null differ
diff --git a/docs/.sphinx/_templates/footer.html b/docs/.sphinx/_templates/footer.html
new file mode 100644
index 0000000..2d118a8
--- /dev/null
+++ b/docs/.sphinx/_templates/footer.html
@@ -0,0 +1,111 @@
+{# ru-fu: copied from Furo, with modifications as stated below. Modifications are marked 'mod:'. #}
+
+<div class="related-pages">
+ {# mod: Per-page navigation #}
+ {% if meta %}
+ {% if 'sequential_nav' in meta %}
+ {% set sequential_nav = meta.sequential_nav %}
+ {% endif %}
+ {% endif %}
+ {# mod: Conditional wrappers to control page navigation buttons #}
+ {% if sequential_nav != "none" -%}
+ {% if next and (sequential_nav == "next" or sequential_nav == "both") -%}
+ <a class="next-page" href="{{ next.link }}">
+ <div class="page-info">
+ <div class="context">
+ <span>{{ _("Next") }}</span>
+ </div>
+ <div class="title">{{ next.title }}</div>
+ </div>
+ <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
+ </a>
+ {%- endif %}
+ {% if prev and (sequential_nav == "prev" or sequential_nav == "both") -%}
+ <a class="prev-page" href="{{ prev.link }}">
+ <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
+ <div class="page-info">
+ <div class="context">
+ <span>{{ _("Previous") }}</span>
+ </div>
+ {% if prev.link == pathto(root_doc) %}
+ <div class="title">{{ _("Home") }}</div>
+ {% else %}
+ <div class="title">{{ prev.title }}</div>
+ {% endif %}
+ </div>
+ </a>
+ {%- endif %}
+ {%- endif %}
+</div>
+<div class="bottom-of-page">
+ <div class="left-details">
+ {%- if show_copyright %}
+ <div class="copyright">
+ {%- if hasdoc('copyright') %}
+ {% trans path=pathto('copyright'), copyright=copyright|e -%}
+ <a href="{{ path }}">Copyright</a> © {{ copyright }}
+ {%- endtrans %}
+ {%- else %}
+ {% trans copyright=copyright|e -%}
+ Copyright © {{ copyright }}
+ {%- endtrans %}
+ {%- endif %}
+ </div>
+ {%- endif %}
+
+ {# mod: removed "Made with" #}
+
+ {%- if last_updated -%}
+ <div class="last-updated">
+ {% trans last_updated=last_updated|e -%}
+ Last updated on {{ last_updated }}
+ {%- endtrans -%}
+ </div>
+ {%- endif %}
+
+ {%- if show_source and has_source and sourcename %}
+ <div class="show-source">
+ <a class="muted-link" href="{{ pathto('_sources/' + sourcename, true)|e }}"
+ rel="nofollow">Show source</a>
+ </div>
+ {%- endif %}
+ </div>
+ <div class="right-details">
+
+ {# mod: replaced RTD icons with our links #}
+
+ {% if discourse %}
+ <div class="ask-discourse">
+ <a class="muted-link" href="{{ discourse }}">Ask a question on Discourse</a>
+ </div>
+ {% endif %}
+
+ {% if irc %}
+ <div class="ask-mattermost">
+ <a class="muted-link" href="{{ irc }}">Ask a question on IRC</a>
+ </div>
+ {% endif %}
+
+ {% if matrix %}
+ <div class="ask-matrix">
+ <a class="muted-link" href="{{ matrix }}">Ask a question on Matrix</a>
+ </div>
+ {% endif %}
+
+ {% if launchpad_url and launchpad_version and launchpad_folder %}
+
+ {% if launchpad_issues %}
+ <div class="issue-github">
+ <a class="muted-link" href="{{ launchpad_issues }}">Open a Launchpad issue for this documentation</a>
+ </div>
+ {% endif %}
+
+ <div class="edit-github">
+ <a class="muted-link" href="{{ launchpad_url }}/tree{{ launchpad_folder }}{{ pagename }}{{ page_source_suffix }}">View this page on Launchpad</a>
+ </div>
+ {% endif %}
+
+
+ </div>
+ </div>
+</div>
diff --git a/docs/.sphinx/_templates/header.html b/docs/.sphinx/_templates/header.html
index 30c52c5..d0ac8e5 100644
--- a/docs/.sphinx/_templates/header.html
+++ b/docs/.sphinx/_templates/header.html
@@ -26,9 +26,9 @@
</li>
{% endif %}
- {% if mattermost %}
+ {% if irc %}
<li>
- <a href="{{ mattermost }}" class="p-navigation__sub-link p-dropdown__link">Mattermost</a>
+ <a href="{{ irc }}" class="p-navigation__sub-link p-dropdown__link">IRC</a>
</li>
{% endif %}
@@ -38,9 +38,9 @@
</li>
{% endif %}
- {% if github_url %}
+ {% if launchpad_url %}
<li>
- <a href="{{ github_url }}" class="p-navigation__sub-link p-dropdown__link">GitHub</a>
+ <a href="{{ launchpad_url }}" class="p-navigation__sub-link p-dropdown__link">Launchpad</a>
</li>
{% endif %}
diff --git a/docs/.sphinx/get_vale_conf.py b/docs/.sphinx/get_vale_conf.py
index 23d8901..cb73a64 100644
--- a/docs/.sphinx/get_vale_conf.py
+++ b/docs/.sphinx/get_vale_conf.py
@@ -3,16 +3,18 @@
import requests
import os
-DIR=os.getcwd()
+DIR = os.getcwd()
def main():
-
if os.path.exists(f"{DIR}/.sphinx/styles/Canonical"):
print("Vale directory exists")
else:
os.makedirs(f"{DIR}/.sphinx/styles/Canonical")
- url = "https://api.github.com/repos/canonical/praecepta/contents/styles/Canonical";
+ url = (
+ "https://api.github.com/repos/canonical/praecepta/";
+ + "contents/styles/Canonical"
+ )
r = requests.get(url)
for item in r.json():
download = requests.get(item["download_url"])
@@ -20,22 +22,47 @@ def main():
file.write(download.text)
file.close()
+ # Update dictionary
+ if os.path.exists(f"{DIR}/.sphinx/styles/config/dictionaries"):
+ print("Dictionary directory exists")
+ else:
+ os.makedirs(f"{DIR}/.sphinx/styles/config/dictionaries")
+ url = (
+ "https://api.github.com/repos/canonical/praecepta/";
+ + "contents/styles/config/dictionaries"
+ )
+ r = requests.get(url)
+ for item in r.json():
+ download = requests.get(item["download_url"])
+ file = open(".sphinx/styles/config/dictionaries/" + item["name"], "w")
+ file.write(download.text)
+ file.close()
+
if os.path.exists(f"{DIR}/.sphinx/styles/config/vocabularies/Canonical"):
print("Vocab directory exists")
else:
os.makedirs(f"{DIR}/.sphinx/styles/config/vocabularies/Canonical")
-
- url = "https://api.github.com/repos/canonical/praecepta/contents/styles/config/vocabularies/Canonical";
+
+ url = (
+ "https://api.github.com/repos/canonical/praecepta/";
+ + "contents/styles/config/vocabularies/Canonical"
+ )
r = requests.get(url)
for item in r.json():
download = requests.get(item["download_url"])
- file = open(".sphinx/styles/config/vocabularies/Canonical/" + item["name"], "w")
+ file = open(
+ ".sphinx/styles/config/vocabularies/Canonical/" + item["name"],
+ "w"
+ )
file.write(download.text)
file.close()
- config = requests.get("https://raw.githubusercontent.com/canonical/praecepta/main/vale.ini";)
+ config = requests.get(
+ "https://raw.githubusercontent.com/canonical/praecepta/main/vale.ini";
+ )
file = open(".sphinx/vale.ini", "w")
file.write(config.text)
file.close()
+
if __name__ == "__main__":
main()
diff --git a/docs/.sphinx/metrics/build_metrics.sh b/docs/.sphinx/metrics/build_metrics.sh
new file mode 100755
index 0000000..bd1ff1c
--- /dev/null
+++ b/docs/.sphinx/metrics/build_metrics.sh
@@ -0,0 +1,15 @@
+#!/bin/bash
+# shellcheck disable=all
+
+links=0
+images=0
+
+# count number of links
+links=$(find . -type d -path './.sphinx' -prune -o -name '*.html' -exec cat {} + | grep -o "<a " | wc -l)
+# count number of images
+images=$(find . -type d -path './.sphinx' -prune -o -name '*.html' -exec cat {} + | grep -o "<img " | wc -l)
+
+# summarise latest metrics
+echo "Summarising metrics for build files (.html)..."
+echo -e "\tlinks: $links"
+echo -e "\timages: $images"
diff --git a/docs/.sphinx/metrics/source_metrics.sh b/docs/.sphinx/metrics/source_metrics.sh
new file mode 100755
index 0000000..07147d6
--- /dev/null
+++ b/docs/.sphinx/metrics/source_metrics.sh
@@ -0,0 +1,66 @@
+#!/bin/bash
+# shellcheck disable=all
+
+VENV=".sphinx/venv/bin/activate"
+
+files=0
+words=0
+readabilityWords=0
+readabilitySentences=0
+readabilitySyllables=0
+readabilityAverage=0
+readable=true
+
+# measure number of files (.rst and .md), excluding those in .sphinx dir
+files=$(find . -type d -path './.sphinx' -prune -o -type f \( -name '*.md' -o -name '*.rst' \) -print | wc -l)
+
+# calculate metrics only if source files are present
+if [ "$files" -eq 0 ]; then
+ echo "There are no source files to calculate metrics"
+else
+ # measure raw total number of words, excluding those in .sphinx dir
+ words=$(find . -type d -path './.sphinx' -prune -o \( -name '*.md' -o -name '*.rst' \) -exec cat {} + | wc -w)
+
+ # calculate readability for markdown source files
+ echo "Activating virtual environment to run vale..."
+ source "${VENV}"
+
+ for file in *.md *.rst; do
+ if [ -f "$file" ]; then
+ readabilityWords=$(vale ls-metrics "$file" | grep '"words"' | sed 's/[^0-9]*//g')
+ readabilitySentences=$(vale ls-metrics "$file" | grep '"sentences"' | sed 's/[^0-9]*//g')
+ readabilitySyllables=$(vale ls-metrics "$file" | grep '"syllables"' | sed 's/[^0-9]*//g')
+ fi
+ done
+
+ echo "Deactivating virtual environment..."
+ deactivate
+
+ # calculate mean number of words
+ if [ "$files" -ge 1 ]; then
+ meanval=$((readabilityWords / files))
+ else
+ meanval=$readabilityWords
+ fi
+
+ readabilityAverage=$(echo "scale=2; 0.39 * ($readabilityWords / $readabilitySentences) + (11.8 * ($readabilitySyllables / $readabilityWords)) - 15.59" | bc)
+
+ # cast average to int for comparison
+ readabilityAverageInt=$(echo "$readabilityAverage / 1" | bc)
+
+ # value below 8 is considered readable
+ if [ "$readabilityAverageInt" -lt 8 ]; then
+ readable=true
+ else
+ readable=false
+ fi
+
+ # summarise latest metrics
+ echo "Summarising metrics for source files (.md, .rst)..."
+ echo -e "\ttotal files: $files"
+ echo -e "\ttotal words (raw): $words"
+ echo -e "\ttotal words (prose): $readabilityWords"
+ echo -e "\taverage word count: $meanval"
+ echo -e "\treadability: $readabilityAverage"
+ echo -e "\treadable: $readable"
+fi
diff --git a/docs/.sphinx/pa11y.json b/docs/.sphinx/pa11y.json
index 8df0cb9..04dc1e1 100644
--- a/docs/.sphinx/pa11y.json
+++ b/docs/.sphinx/pa11y.json
@@ -6,4 +6,4 @@
},
"reporter": "cli",
"standard": "WCAG2AA"
-}
\ No newline at end of file
+}
diff --git a/docs/.sphinx/requirements.txt b/docs/.sphinx/requirements.txt
index c019f17..9ff666c 100644
--- a/docs/.sphinx/requirements.txt
+++ b/docs/.sphinx/requirements.txt
@@ -1,2 +1,4 @@
-git+https://github.com/canonical/canonical-sphinx@main#egg=canonical-sphinx
+canonical-sphinx[full]
sphinx-autobuild
+sphinxcontrib-svg2pdfconverter[CairoSVG]
+sphinx-last-updated-by-git
diff --git a/docs/.sphinx/spellingcheck.yaml b/docs/.sphinx/spellingcheck.yaml
index 5f3dbad..9ee9ae7 100644
--- a/docs/.sphinx/spellingcheck.yaml
+++ b/docs/.sphinx/spellingcheck.yaml
@@ -1,30 +1,30 @@
matrix:
-- name: rST files
- aspell:
- lang: en
- d: en_GB
- dictionary:
- wordlists:
- - .sphinx/.wordlist.txt
- - .custom_wordlist.txt
- output: .sphinx/.wordlist.dic
- sources:
- - _build/**/*.html
- pipeline:
- - pyspelling.filters.html:
- comments: false
- attributes:
- - title
- - alt
- ignores:
- - code
- - pre
- - spellexception
- - link
- - title
- - div.relatedlinks
- - strong.command
- - div.visually-hidden
- - img
- - a.p-navigation__link
- - a.contributor
+ - name: rST files
+ aspell:
+ lang: en
+ d: en_GB
+ dictionary:
+ wordlists:
+ - .sphinx/.wordlist.txt
+ - .custom_wordlist.txt
+ output: .sphinx/.wordlist.dic
+ sources:
+ - _build/**/*.html
+ pipeline:
+ - pyspelling.filters.html:
+ comments: false
+ attributes:
+ - title
+ - alt
+ ignores:
+ - code
+ - pre
+ - spellexception
+ - link
+ - title
+ - div.relatedlinks
+ - strong.command
+ - div.visually-hidden
+ - img
+ - a.p-navigation__link
+ - a.contributor
diff --git a/docs/Makefile b/docs/Makefile
index a861ba8..b9bdea0 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -1,11 +1,23 @@
-# This Makefile stub allows you to customize starter pack (SP) targets.
-# Consider this file as a bridge between your project
-# and the starter pack's predefined targets that reside in Makefile.sp.
+# Minimal makefile for Sphinx documentation
#
-# You can add your own, non-SP targets here or override SP targets
-# to fit your project's needs. For example, you can define and use targets
-# named "install" or "run", but continue to use SP targets like "sp-install"
-# or "sp-run" when working on the documentation.
+# Add your customisation to `Makefile` instead.
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXDIR = .sphinx
+SPHINXOPTS ?= -c . -d $(SPHINXDIR)/.doctrees -j auto
+SPHINXBUILD ?= $(VENVDIR)/bin/sphinx-build
+SOURCEDIR = .
+BUILDDIR = _build
+VENVDIR = $(SPHINXDIR)/venv
+PA11Y = $(SPHINXDIR)/node_modules/pa11y/bin/pa11y.js --config $(SPHINXDIR)/pa11y.json
+VENV = $(VENVDIR)/bin/activate
+TARGET = *
+ALLFILES = *.rst **/*.rst
+METRICSDIR = $(SOURCEDIR)/.sphinx/metrics
+REQPDFPACKS = latexmk fonts-freefont-otf texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-font-utils texlive-lang-cjk texlive-xetex plantuml xindy tex-gyre dvipng
+CONFIRM_SUDO ?= N
+VALE_CONFIG = $(SPHINXDIR)/vale.ini
# Put it first so that "make" without argument is like "make help".
help:
@@ -23,8 +35,153 @@ help:
"* check accessibility: make pa11y \n" \
"* check style guide compliance: make vale \n" \
"* check style guide compliance on target: make vale TARGET=* \n" \
+ "* check metrics for documentation: make allmetrics \n" \
"* other possible targets: make <TAB twice> \n" \
"------------------------------------------------------------- \n"
+.PHONY: full-help woke-install spellcheck-install pa11y-install install run html \
+ epub serve clean clean-doc spelling spellcheck linkcheck woke \
+ allmetrics pa11y pdf-prep-force pdf-prep pdf vale-install vale
+
+full-help: $(VENVDIR)
+ @. $(VENV); $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+ @echo "\n\033[1;31mNOTE: This help texts shows unsupported targets!\033[0m"
+ @echo "Run 'make help' to see supported targets."
+
+# If requirements are updated, venv should be rebuilt and timestamped.
+$(VENVDIR):
+ python3 -c "import venv" || \
+ (echo "You must install python3-venv before you can build the documentation."; exit 1)
+ @echo "... setting up virtualenv"
+ python3 -m venv $(VENVDIR)
+ . $(VENV); pip install $(PIPOPTS) --require-virtualenv \
+ --upgrade -r $(SPHINXDIR)/requirements.txt \
+ --log $(VENVDIR)/pip_install.log
+ @test ! -f $(VENVDIR)/pip_list.txt || \
+ mv $(VENVDIR)/pip_list.txt $(VENVDIR)/pip_list.txt.bak
+ @. $(VENV); pip list --local --format=freeze > $(VENVDIR)/pip_list.txt
+ @touch $(VENVDIR)
+
+spellcheck-install:
+ @type aspell >/dev/null 2>&1 || \
+ { \
+ echo "Installing system-wide \"aspell\" packages..."; \
+ confirm_sudo=$(CONFIRM_SUDO); \
+ if [ "$$confirm_sudo" != "y" ] && [ "$$confirm_sudo" != "Y" ]; then \
+ read -p "This requires sudo privileges. Proceed? [y/N]: " confirm_sudo; \
+ fi; \
+ if [ "$$confirm_sudo" = "y" ] || [ "$$confirm_sudo" = "Y" ]; then \
+ sudo apt-get install aspell aspell-en; \
+ else \
+ echo "Installation cancelled."; \
+ fi \
+ }
+
+pa11y-install:
+ @type $(PA11Y) >/dev/null 2>&1 || { \
+ echo "Installing \"pa11y\" from npm... \n"; \
+ mkdir -p $(SPHINXDIR)/node_modules/ ; \
+ npm install --prefix $(SPHINXDIR) pa11y; \
+ }
+
+install: $(VENVDIR)
+
+run: install
+ . $(VENV); $(VENVDIR)/bin/sphinx-autobuild -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
+# Doesn't depend on $(BUILDDIR) to rebuild properly at every run.
+html: install
+ . $(VENV); $(SPHINXBUILD) -W --keep-going -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS)
+
+epub: install
+ . $(VENV); $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS)
+
+serve: html
+ cd "$(BUILDDIR)"; python3 -m http.server --bind 127.0.0.1 8000
+
+clean: clean-doc
+ @test ! -e "$(VENVDIR)" -o -d "$(VENVDIR)" -a "$(abspath $(VENVDIR))" != "$(VENVDIR)"
+ rm -rf $(VENVDIR)
+ rm -rf $(SPHINXDIR)/node_modules/
+ rm -rf $(SPHINXDIR)/styles
+ rm -rf $(VALE_CONFIG)
+
+clean-doc:
+ git clean -fx "$(BUILDDIR)"
+ rm -rf $(SPHINXDIR)/.doctrees
+
+spellcheck: spellcheck-install
+ . $(VENV) ; python3 -m pyspelling -c $(SPHINXDIR)/spellingcheck.yaml -j $(shell nproc)
+
+spelling: html spellcheck
+
+linkcheck: install
+ . $(VENV) ; $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) || { grep --color -F "[broken]" "$(BUILDDIR)/output.txt"; exit 1; }
+ exit 0
+
+pa11y: pa11y-install html
+ find $(BUILDDIR) -name *.html -print0 | xargs -n 1 -0 $(PA11Y)
+
+vale-install: install
+ @. $(VENV); test -d $(SPHINXDIR)/venv/lib/python*/site-packages/vale || pip install rst2html vale
+ @. $(VENV); test -f $(VALE_CONFIG) || python3 $(SPHINXDIR)/get_vale_conf.py
+ @printf '.Name=="Canonical.400-Enforce-inclusive-terms"' > $(SPHINXDIR)/styles/woke.filter
+ @printf '.Level=="error" and .Name!="Canonical.500-Repeated-words" and .Name!="Canonical.000-US-spellcheck"' > $(SPHINXDIR)/styles/error.filter
+ @printf '.Name=="Canonical.000-US-spellcheck"' > $(SPHINXDIR)/styles/spelling.filter
+ @. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --config "$(VALE_CONFIG)" $(TARGET) > /dev/null \;
+
+woke: vale-install
+ @cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt
+ @cat $(SPHINXDIR)/.wordlist.txt $(SOURCEDIR)/.custom_wordlist.txt >> $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt
+ @printf "Running Vale acceptable term check against $(TARGET). To change target set TARGET= with make command\n"
+ @. $(VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINXDIR)/styles/woke.filter' --glob='*.{md,rst}' $(TARGET) || true
+ @cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt && rm $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt
+
+vale: vale-install
+ @cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt
+ @cat $(SPHINXDIR)/.wordlist.txt $(SOURCEDIR)/.custom_wordlist.txt >> $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt
+ @printf "Running Vale against $(TARGET). To change target set TARGET= with make command\n"
+ @. $(VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINXDIR)/styles/error.filter' --glob='*.{md,rst}' $(TARGET) || true
+ @cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt && rm $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt
+
+vale-spelling: vale-install
+ @cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt
+ @cat $(SPHINXDIR)/.wordlist.txt $(SOURCEDIR)/.custom_wordlist.txt >> $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt
+ @printf "Running Vale against $(TARGET). To change target set TARGET= with make command\n"
+ @. $(VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINXDIR)/styles/spelling.filter' --glob='*.{md,rst}' $(TARGET) || true
+ @cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt && rm $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt
+
+pdf-prep: install
+ @for packageName in $(REQPDFPACKS); do (dpkg-query -W -f='$${Status}' $$packageName 2>/dev/null | \
+ grep -c "ok installed" >/dev/null && echo "Package $$packageName is installed") && continue || \
+ (echo "\nPDF generation requires the installation of the following packages: $(REQPDFPACKS)" && \
+ echo "" && echo "Run 'sudo make pdf-prep-force' to install these packages" && echo "" && echo \
+ "Please be aware these packages will be installed to your system") && exit 1 ; done
+
+pdf-prep-force:
+ apt-get update
+ apt-get upgrade -y
+ apt-get install --no-install-recommends -y $(REQPDFPACKS) \
+
+pdf: pdf-prep
+ @. $(VENV); sphinx-build -M latexpdf "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+ @rm ./$(BUILDDIR)/latex/front-page-light.pdf || true
+ @rm ./$(BUILDDIR)/latex/normal-page-footer.pdf || true
+ @find ./$(BUILDDIR)/latex -name "*.pdf" -exec mv -t ./$(BUILDDIR) {} +
+ @rm -r $(BUILDDIR)/latex
+ @echo "\nOutput can be found in ./$(BUILDDIR)\n"
+
+allmetrics: html
+ @echo "Recording documentation metrics..."
+ @echo "Checking for existence of vale..."
+ . $(VENV)
+ @. $(VENV); test -d $(SPHINXDIR)/venv/lib/python*/site-packages/vale || pip install vale
+ @. $(VENV); test -f $(VALE_CONFIG) || python3 $(SPHINXDIR)/get_vale_conf.py
+ @. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --config "$(VALE_CONFIG)" $(TARGET) > /dev/null \;
+ @eval '$(METRICSDIR)/source_metrics.sh $(PWD)'
+ @eval '$(METRICSDIR)/build_metrics.sh $(PWD) $(METRICSDIR)'
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%:
- $(MAKE) -f Makefile.sp sp-$@
+ . $(VENV); $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/Makefile.sp b/docs/Makefile.sp
deleted file mode 100644
index 80b5141..0000000
--- a/docs/Makefile.sp
+++ /dev/null
@@ -1,114 +0,0 @@
-# Minimal makefile for Sphinx documentation
-#
-# `Makefile.sp` is from the Sphinx starter pack and should not be
-# modified.
-# Add your customisation to `Makefile` instead.
-
-# You can set these variables from the command line, and also
-# from the environment for the first two.
-SPHINXDIR = .sphinx
-SPHINXOPTS ?= -c . -d $(SPHINXDIR)/.doctrees -j auto
-SPHINXBUILD ?= $(VENVDIR)/bin/sphinx-build
-SOURCEDIR = .
-BUILDDIR = _build
-VENVDIR = $(SPHINXDIR)/venv
-PA11Y = $(SPHINXDIR)/node_modules/pa11y/bin/pa11y.js --config $(SPHINXDIR)/pa11y.json
-VENV = $(VENVDIR)/bin/activate
-TARGET = *
-ALLFILES = *.rst **/*.rst
-
-.PHONY: sp-full-help sp-woke-install sp-spellcheck-install sp-pa11y-install sp-install sp-run sp-html \
- sp-epub sp-serve sp-clean sp-clean-doc sp-spelling sp-spellcheck sp-linkcheck sp-woke \
- sp-pa11y Makefile.sp sp-vale
-
-sp-full-help: $(VENVDIR)
- @. $(VENV); $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
- @echo "\n\033[1;31mNOTE: This help texts shows unsupported targets!\033[0m"
- @echo "Run 'make help' to see supported targets."
-
-# If requirements are updated, venv should be rebuilt and timestamped.
-$(VENVDIR):
- python3 -c "import venv" || \
- (echo "You must install python3-venv before you can build the documentation."; exit 1)
- @echo "... setting up virtualenv"
- python3 -m venv $(VENVDIR)
- . $(VENV); pip install --require-virtualenv \
- --upgrade -r $(SPHINXDIR)/requirements.txt \
- --log $(VENVDIR)/pip_install.log
- @test ! -f $(VENVDIR)/pip_list.txt || \
- mv $(VENVDIR)/pip_list.txt $(VENVDIR)/pip_list.txt.bak
- @. $(VENV); pip list --local --format=freeze > $(VENVDIR)/pip_list.txt
- @touch $(VENVDIR)
-
-sp-woke-install:
- @type woke >/dev/null 2>&1 || \
- { echo "Installing \"woke\" snap... \n"; sudo snap install woke; }
-
-sp-spellcheck-install:
- @type aspell >/dev/null 2>&1 || \
- { echo "Installing aspell... \n"; sudo apt-get install aspell aspell-en; }
-
-sp-pa11y-install:
- @type $(PA11Y) >/dev/null 2>&1 || { \
- echo "Installing \"pa11y\" from npm... \n"; \
- mkdir -p $(SPHINXDIR)/node_modules/ ; \
- npm install --prefix $(SPHINXDIR) pa11y; \
- }
-
-sp-install: $(VENVDIR)
-
-sp-run: sp-install
- . $(VENV); $(VENVDIR)/bin/sphinx-autobuild -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
-
-# Doesn't depend on $(BUILDDIR) to rebuild properly at every run.
-sp-html: sp-install
- . $(VENV); $(SPHINXBUILD) -W --keep-going -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS)
-
-sp-epub: sp-install
- . $(VENV); $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS)
-
-sp-serve: sp-html
- cd "$(BUILDDIR)"; python3 -m http.server --bind 127.0.0.1 8000
-
-sp-clean: sp-clean-doc
- @test ! -e "$(VENVDIR)" -o -d "$(VENVDIR)" -a "$(abspath $(VENVDIR))" != "$(VENVDIR)"
- rm -rf $(VENVDIR)
- rm -rf $(SPHINXDIR)/node_modules/
- rm -rf $(SPHINXDIR)/styles
- rm -rf $(SPHINXDIR)/vale.ini
-
-sp-clean-doc:
- git clean -fx "$(BUILDDIR)"
- rm -rf $(SPHINXDIR)/.doctrees
-
-sp-spellcheck: sp-spellcheck-install
- . $(VENV) ; python3 -m pyspelling -c $(SPHINXDIR)/spellingcheck.yaml -j $(shell nproc)
-
-sp-spelling: sp-html sp-spellcheck
-
-sp-linkcheck: sp-install
- . $(VENV) ; $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) || { grep --color -F "[broken]" "$(BUILDDIR)/output.txt"; exit 1; }
- exit 0
-
-sp-woke: sp-woke-install
- woke $(ALLFILES) --exit-1-on-failure \
- -c https://github.com/canonical/Inclusive-naming/raw/main/config.yml
-
-sp-pa11y: sp-pa11y-install sp-html
- find $(BUILDDIR) -name *.html -print0 | xargs -n 1 -0 $(PA11Y)
-
-sp-vale: sp-install
- @. $(VENV); test -d $(SPHINXDIR)/venv/lib/python*/site-packages/vale || pip install vale
- @. $(VENV); test -f $(SPHINXDIR)/vale.ini || python3 $(SPHINXDIR)/get_vale_conf.py
- @. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --config "$(SPHINXDIR)/vale.ini" $(TARGET) > /dev/null \;
- @echo ""
- @echo "Running Vale against $(TARGET). To change target set TARGET= with make command"
- @echo ""
- @. $(VENV); vale --config "$(SPHINXDIR)/vale.ini" --glob='*.{md,txt,rst}' $(TARGET)
-
-
-
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile.sp
- . $(VENV); $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/conf.py b/docs/conf.py
index a8b1cd9..c8e6449 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -82,37 +82,24 @@ html_context = {
# (use an empty value if you don't want to link)
'discourse': 'https://discourse.ubuntu.com',
- # Change to the Mattermost channel you want to link to
- # (use an empty value if you don't want to link)
- 'mattermost': '',
-
- # Change to the Matrix channel you want to link to
- # (use an empty value if you don't want to link)
- 'matrix': '',
-
- # Change to the GitHub URL for your project
- # This is used, for example, to link to the source files and allow creating GitHub issues directly from the documentation.
- 'github_url': 'https://launchpad.net/~techboard/ubuntu-governance-docs',
-
+ # Your IRC channel
+ "irc": "https://web.libera.chat/gamja/?channels=%23ubuntu-devel";,
+ # Your Matrix channel URL
+ "matrix": "https://matrix.to/#/#devel:ubuntu.com";,
+ # Your Launchpad URL
+ "launchpad_url": "https://git.launchpad.net/ubuntu-governance-docs";,
# Change to the branch for this version of the documentation
- 'github_version': 'main',
-
+ "launchpad_version": "main",
# Change to the folder that contains the documentation
# (usually "/" or "/docs/")
- 'github_folder': '/docs/',
-
- # Change to an empty value if your GitHub repo doesn't have issues enabled.
- # This will disable the feedback button and the issue link in the footer.
- 'github_issues': '',
-
+ "launchpad_folder": "/docs/",
+ # Change to an empty value to disable the issue link in the footer.
+ "launchpad_issues": "https://bugs.launchpad.net/ubuntu-governance-docs/+filebug";,
# Controls the existence of Previous / Next buttons at the bottom of pages
# Valid options: none, prev, next, both
- # 'sequential_nav': "none",
-
- # Uncomment to disable displaying the contributors for each file.
- # (You can also limit the time frame for displaying contributors
- # by setting a "display_contributors_since" variable.)
- # "display_contributors": False,
+ "sequential_nav": "both",
+ # Controls whether to display the contributors for each file
+ "display_contributors": False,
}
@@ -178,12 +165,13 @@ myst_enable_extensions = {
# If you need more extensions, add them here (in addition to
# canonical_sphinx).
extensions = [
- 'canonical_sphinx'
+ "canonical_sphinx",
+ "sphinxcontrib.cairosvgconverter",
+ "sphinx_last_updated_by_git",
]
# Add files or directories that should be excluded from processing.
exclude_patterns = [
- 'doc-cheat-sheet*',
]
# Add custom CSS files (located in .sphinx/_static/)
--
technical-board mailing list
technical-board@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/technical-board
