Skip to content
This repository was archived by the owner on Feb 13, 2025. It is now read-only.

Commit 56a20e5

Browse files
tmihoctmihoc
committed
Add all files
1 parent 5fb1e94 commit 56a20e5

21 files changed

+1241
-0
lines changed

‎.custom_wordlist.txt

Whitespace-only changes.

‎.github/workflows/automatic-doc-checks.yml

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
name: Main Documentation Checks
2+
3+
on:
4+
- push
5+
- pull_request
6+
- workflow_dispatch
7+
8+
concurrency:
9+
group: ${{ github.workflow }}-${{ github.ref }}
10+
cancel-in-progress: true
11+
12+
jobs:
13+
documentation-checks:
14+
uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main
15+
with:
16+
working-directory: '.'

‎.gitignore

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
2+
# Starter pack rules start here
3+
/*env*/
4+
.sphinx/venv/
5+
.sphinx/warnings.txt
6+
.sphinx/.wordlist.dic
7+
.sphinx/.doctrees/
8+
.sphinx/node_modules/
9+
package*.json
10+
_build
11+
.DS_Store
12+
__pycache__
13+
.idea/
14+
.vscode/
15+
.sphinx/styles/*
16+
.sphinx/vale.ini

‎.readthedocs.yaml

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# .readthedocs.yaml
2+
# Read the Docs configuration file
3+
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
4+
5+
# Required
6+
version: 2
7+
8+
# Set the version of Python and other tools you might need
9+
build:
10+
os: ubuntu-22.04
11+
tools:
12+
python: "3.11"
13+
jobs:
14+
pre_install:
15+
- git fetch --unshallow || true
16+
17+
# Build documentation in the docs/ directory with Sphinx
18+
sphinx:
19+
builder: dirhtml
20+
configuration: ./conf.py
21+
fail_on_warning: true
22+
23+
# If using Sphinx, optionally build your docs in additional formats such as PDF
24+
formats:
25+
- pdf
26+
27+
# Optionally declare the Python requirements required to build your docs
28+
python:
29+
install:
30+
- requirements: ./.sphinx/requirements.txt

‎.sphinx/.wordlist.txt

+61
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# This wordlist is from the Sphinx starter pack and should not be
2+
# modified. Add any custom terms to .custom_wordlist.txt instead.
3+
4+
addons
5+
API
6+
APIs
7+
balancer
8+
Charmhub
9+
CLI
10+
Diátaxis
11+
dropdown
12+
EBS
13+
EKS
14+
enablement
15+
favicon
16+
Furo
17+
Git
18+
GitHub
19+
Grafana
20+
IAM
21+
installable
22+
JSON
23+
Juju
24+
Kubeflow
25+
Kubernetes
26+
Launchpad
27+
linter
28+
LTS
29+
LXD
30+
Makefile
31+
Makefiles
32+
Matrix
33+
Mattermost
34+
MicroCeph
35+
MicroCloud
36+
MicroOVN
37+
MyST
38+
namespace
39+
namespaces
40+
NodePort
41+
Numbat
42+
observability
43+
OEM
44+
OLM
45+
Permalink
46+
pre
47+
Quickstart
48+
ReadMe
49+
reST
50+
reStructuredText
51+
roadmap
52+
RTD
53+
subdirectories
54+
subfolders
55+
subtree
56+
Ubuntu
57+
UI
58+
UUID
59+
VM
60+
webhook
61+
YAML

‎.sphinx/_static/favicon.png

2.21 KB
Loading

‎.sphinx/_static/tag.png

6.62 KB
Loading

‎.sphinx/_templates/header.html

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
<header id="header" class="p-navigation">
2+
3+
<div class="p-navigation__nav" role="menubar">
4+
5+
<ul class="p-navigation__links" role="menu">
6+
7+
<li>
8+
<a class="p-logo" href="https://{{ product_page }}" aria-current="page">
9+
<img src="{{ pathto(product_tag,1) }}" alt="Logo" class="p-logo-image">
10+
<div class="p-logo-text p-heading--4">{{ project }}
11+
</div>
12+
</a>
13+
</li>
14+
15+
<li class="nav-ubuntu-com">
16+
<a href="https://{{ product_page }}" class="p-navigation__link">{{ product_page }}</a>
17+
</li>
18+
19+
<li>
20+
<a href="#" class="p-navigation__link nav-more-links">More resources</a>
21+
<ul class="more-links-dropdown">
22+
23+
<li>
24+
<a href="{{ discourse }}" class="p-navigation__sub-link p-dropdown__link">Forum</a>
25+
</li>
26+
27+
<li>
28+
<a href="{{ github_url }}" class="p-navigation__sub-link p-dropdown__link">GitHub</a>
29+
</li>
30+
31+
</ul>
32+
</li>
33+
34+
</ul>
35+
</div>
36+
</header>

‎.sphinx/get_vale_conf.py

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
#! /usr/bin/env python
2+
3+
import requests
4+
import os
5+
6+
DIR=os.getcwd()
7+
8+
def main():
9+
10+
if os.path.exists(f"{DIR}/.sphinx/styles/Canonical"):
11+
print("Vale directory exists")
12+
else:
13+
os.makedirs(f"{DIR}/.sphinx/styles/Canonical")
14+
15+
url = "https://api.github.com/repos/canonical/praecepta/contents/styles/Canonical"
16+
r = requests.get(url)
17+
for item in r.json():
18+
download = requests.get(item["download_url"])
19+
file = open(".sphinx/styles/Canonical/" + item["name"], "w")
20+
file.write(download.text)
21+
file.close()
22+
23+
config = requests.get("https://raw.githubusercontent.com/canonical/praecepta/main/vale.ini")
24+
file = open(".sphinx/vale.ini", "w")
25+
file.write(config.text)
26+
file.close()
27+
28+
if __name__ == "__main__":
29+
main()

‎.sphinx/pa11y.json

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"chromeLaunchConfig": {
3+
"args": [
4+
"--no-sandbox"
5+
]
6+
},
7+
"reporter": "cli",
8+
"standard": "WCAG2AA"
9+
}

‎.sphinx/requirements.txt

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
git+https://github.com/canonical/canonical-sphinx@main#egg=canonical-sphinx
2+
sphinx-autobuild

‎.sphinx/spellingcheck.yaml

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
matrix:
2+
- name: rST files
3+
aspell:
4+
lang: en
5+
d: en_GB
6+
dictionary:
7+
wordlists:
8+
- .sphinx/.wordlist.txt
9+
- .custom_wordlist.txt
10+
output: .sphinx/.wordlist.dic
11+
sources:
12+
- _build/**/*.html
13+
pipeline:
14+
- pyspelling.filters.html:
15+
comments: false
16+
attributes:
17+
- title
18+
- alt
19+
ignores:
20+
- code
21+
- pre
22+
- spellexception
23+
- link
24+
- title
25+
- div.relatedlinks
26+
- strong.command
27+
- div.visually-hidden
28+
- img
29+
- a.p-navigation__link
30+
- a.contributor

‎.wokeignore

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# the cheat sheets contain a link to a repository with a block word which we
2+
# cannot avoid for now, ie
3+
# https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
4+
doc-cheat-sheet*

‎Makefile

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# This Makefile stub allows you to customize starter pack (SP) targets.
2+
# Consider this file as a bridge between your project
3+
# and the starter pack's predefined targets that reside in Makefile.sp.
4+
#
5+
# You can add your own, non-SP targets here or override SP targets
6+
# to fit your project's needs. For example, you can define and use targets
7+
# named "install" or "run", but continue to use SP targets like "sp-install"
8+
# or "sp-run" when working on the documentation.
9+
10+
# Put it first so that "make" without argument is like "make help".
11+
help:
12+
@echo "\n" \
13+
"------------------------------------------------------------- \n" \
14+
"* watch, build and serve the documentation: make run \n" \
15+
"* only build: make html \n" \
16+
"* only serve: make serve \n" \
17+
"* clean built doc files: make clean-doc \n" \
18+
"* clean full environment: make clean \n" \
19+
"* check links: make linkcheck \n" \
20+
"* check spelling: make spelling \n" \
21+
"* check spelling (without building again): make spellcheck \n" \
22+
"* check inclusive language: make woke \n" \
23+
"* check accessibility: make pa11y \n" \
24+
"* check style guide compliance: make vale \n" \
25+
"* check style guide compliance on target: make vale TARGET=* \n" \
26+
"* other possible targets: make <TAB twice> \n" \
27+
"------------------------------------------------------------- \n"
28+
29+
%:
30+
$(MAKE) -f Makefile.sp sp-$@

‎Makefile.sp

+110
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
# `Makefile.sp` is from the Sphinx starter pack and should not be
4+
# modified.
5+
# Add your customisation to `Makefile` instead.
6+
7+
# You can set these variables from the command line, and also
8+
# from the environment for the first two.
9+
SPHINXDIR = .sphinx
10+
SPHINXOPTS ?= -c . -d $(SPHINXDIR)/.doctrees
11+
SPHINXBUILD ?= $(VENVDIR)/bin/sphinx-build
12+
SOURCEDIR = .
13+
BUILDDIR = _build
14+
VENVDIR = $(SPHINXDIR)/venv
15+
PA11Y = $(SPHINXDIR)/node_modules/pa11y/bin/pa11y.js --config $(SPHINXDIR)/pa11y.json
16+
VENV = $(VENVDIR)/bin/activate
17+
TARGET = *
18+
ALLFILES = *.rst **/*.rst
19+
20+
.PHONY: sp-full-help sp-woke-install sp-pa11y-install sp-install sp-run sp-html \
21+
sp-epub sp-serve sp-clean sp-clean-doc sp-spelling sp-spellcheck sp-linkcheck sp-woke \
22+
sp-pa11y Makefile.sp sp-vale
23+
24+
sp-full-help: $(VENVDIR)
25+
@. $(VENV); $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
26+
@echo "\n\033[1;31mNOTE: This help texts shows unsupported targets!\033[0m"
27+
@echo "Run 'make help' to see supported targets."
28+
29+
# If requirements are updated, venv should be rebuilt and timestamped.
30+
$(VENVDIR):
31+
python3 -c "import venv" || \
32+
(echo "You must install python3-venv before you can build the documentation."; exit 1)
33+
@echo "... setting up virtualenv"
34+
python3 -m venv $(VENVDIR)
35+
. $(VENV); pip install --require-virtualenv \
36+
--upgrade -r $(SPHINXDIR)/requirements.txt \
37+
--log $(VENVDIR)/pip_install.log
38+
@test ! -f $(VENVDIR)/pip_list.txt || \
39+
mv $(VENVDIR)/pip_list.txt $(VENVDIR)/pip_list.txt.bak
40+
@. $(VENV); pip list --local --format=freeze > $(VENVDIR)/pip_list.txt
41+
@touch $(VENVDIR)
42+
43+
sp-woke-install:
44+
@type woke >/dev/null 2>&1 || \
45+
{ echo "Installing \"woke\" snap... \n"; sudo snap install woke; }
46+
47+
sp-pa11y-install:
48+
@type $(PA11Y) >/dev/null 2>&1 || { \
49+
echo "Installing \"pa11y\" from npm... \n"; \
50+
mkdir -p $(SPHINXDIR)/node_modules/ ; \
51+
npm install --prefix $(SPHINXDIR) pa11y; \
52+
}
53+
54+
sp-install: $(VENVDIR)
55+
56+
sp-run: sp-install
57+
. $(VENV); $(VENVDIR)/bin/sphinx-autobuild -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
58+
59+
# Doesn't depend on $(BUILDDIR) to rebuild properly at every run.
60+
sp-html: sp-install
61+
. $(VENV); $(SPHINXBUILD) -W --keep-going -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS)
62+
63+
sp-epub: sp-install
64+
. $(VENV); $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS)
65+
66+
sp-serve: sp-html
67+
cd "$(BUILDDIR)"; python3 -m http.server --bind 127.0.0.1 8000
68+
69+
sp-clean: sp-clean-doc
70+
@test ! -e "$(VENVDIR)" -o -d "$(VENVDIR)" -a "$(abspath $(VENVDIR))" != "$(VENVDIR)"
71+
rm -rf $(VENVDIR)
72+
rm -rf $(SPHINXDIR)/node_modules/
73+
rm -rf $(SPHINXDIR)/styles
74+
rm -rf $(SPHINXDIR)/vale.ini
75+
76+
sp-clean-doc:
77+
git clean -fx "$(BUILDDIR)"
78+
rm -rf $(SPHINXDIR)/.doctrees
79+
80+
sp-spellcheck:
81+
. $(VENV) ; python3 -m pyspelling -c $(SPHINXDIR)/spellingcheck.yaml -j $(shell nproc)
82+
83+
sp-spelling: sp-html sp-spellcheck
84+
85+
sp-linkcheck: sp-install
86+
. $(VENV) ; $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) || { grep --color -F "[broken]" "$(BUILDDIR)/output.txt"; exit 1; }
87+
exit 0
88+
89+
sp-woke: sp-woke-install
90+
woke $(ALLFILES) --exit-1-on-failure \
91+
-c https://github.com/canonical/Inclusive-naming/raw/main/config.yml
92+
93+
sp-pa11y: sp-pa11y-install sp-html
94+
find $(BUILDDIR) -name *.html -print0 | xargs -n 1 -0 $(PA11Y)
95+
96+
sp-vale: sp-install
97+
@. $(VENV); test -d $(SPHINXDIR)/venv/lib/python*/site-packages/vale || pip install vale
98+
@. $(VENV); test -f $(SPHINXDIR)/vale.ini || python3 $(SPHINXDIR)/get_vale_conf.py
99+
@. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --config "$(SPHINXDIR)/vale.ini" $(TARGET) > /dev/null \;
100+
@echo ""
101+
@echo "Running Vale against $(TARGET). To change target set TARGET= with make command"
102+
@echo ""
103+
@. $(VENV); vale --config "$(SPHINXDIR)/vale.ini" --glob='*.{md,txt,rst}' $(TARGET)
104+
105+
106+
107+
# Catch-all target: route all unknown targets to Sphinx using the new
108+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
109+
%: Makefile.sp
110+
. $(VENV); $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

0 commit comments

Comments
 (0)