Skip to content

Commit 1225849

Browse files
edibotopicedibotopic
committed
initialise docs
- migrates content from wiki - includes boilerplate for RTD hosting - adds automated doc checks
1 parent 23a7e0d commit 1225849

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

47 files changed

+1752
-0
lines changed

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

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

‎.github/workflows/markdown-style-checks.yml

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
name: "Linter for Markdown"
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
pull_request:
8+
branches:
9+
- '*'
10+
11+
jobs:
12+
markdown-lint:
13+
runs-on: ubuntu-22.04
14+
steps:
15+
- uses: actions/checkout@v4
16+
with:
17+
fetch-depth: 0
18+
- uses: DavidAnson/markdownlint-cli2-action@v16
19+
with:
20+
config: "docs/.sphinx/.markdownlint.json"
21+

‎.github/workflows/periodic-style-checks.yml

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
name: Periodic Style Checks
2+
3+
on:
4+
schedule:
5+
- cron: "0 1 * * 4" # Runs at 01:00 AM on every Wednesday
6+
7+
jobs:
8+
vale:
9+
name: Style checker
10+
runs-on: ubuntu-22.04
11+
defaults:
12+
run:
13+
shell: bash
14+
working-directory: "sp-docs"
15+
steps:
16+
- uses: actions/checkout@v4
17+
- name: Run vale
18+
run: |
19+
make vale

‎.github/workflows/sphinx-python-dependency-build-checks.yml

+48
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# The purpose of this workflow file is to confirm that the Sphinx
2+
# virtual environment can be built from source, consequently documenting
3+
# the packages required in the build environment to do that.
4+
#
5+
# This is needed because some projects embeds the documentation into built
6+
# artifacts which involves rendering the documentation on the target
7+
# architecture.
8+
#
9+
# Depending on the architecture, pip may or may not have already built wheels
10+
# available, and as such we need to make sure building wheels from source can
11+
# succeed.
12+
name: Check and document build requirements for Sphinx venv
13+
on:
14+
- push
15+
- pull_request
16+
- workflow_dispatch
17+
18+
concurrency:
19+
group: ${{ github.workflow }}-${{ github.ref }}
20+
cancel-in-progress: true
21+
22+
jobs:
23+
build:
24+
name: build
25+
runs-on: ubuntu-latest
26+
steps:
27+
- name: Checkout code
28+
uses: actions/checkout@v4
29+
30+
- name: Install dependencies
31+
run: |
32+
set -ex
33+
sudo apt -y install \
34+
cargo \
35+
libpython3-dev \
36+
libxml2-dev \
37+
libxslt1-dev \
38+
make \
39+
python3-venv \
40+
rustc
41+
- name: Build Sphinx venv
42+
working-directory: "docs"
43+
run: |
44+
set -ex
45+
make -f docs/Makefile.sp \
46+
sp-install \
47+
PIPOPTS="--no-binary :all:" \
48+
|| ( cat .sphinx/venv/pip_install.log && exit 1 )

‎.wokeignore

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
docs/.wokeignore

‎docs/.custom_wordlist.txt

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
auth
2+
authd
3+
biometric
4+
DBus
5+
entra
6+
GDM
7+
GIDs
8+
gRPC
9+
github
10+
grpc
11+
https
12+
io
13+
msentraid
14+
NFS
15+
nss
16+
OIDC
17+
OpenID
18+
ppa
19+
PR
20+
protoc
21+
PRs
22+
repo
23+
smartcard
24+
sshd
25+
styleguide
26+
sudo
27+
TPM
28+
ubuntu
29+
UID
30+
UIDs
31+
unix
32+
vendorize
33+
vhs
34+
webview
35+
whitespace

‎docs/.gitignore

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
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
17+
sp-docs/_build

‎docs/.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: docs/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: docs/.sphinx/requirements.txt

‎docs/.sphinx/.markdownlint.json

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
{
2+
"default": false,
3+
"MD003": { "style": "atx" },
4+
"MD013": { "code_blocks": false, "tables": false, "stern": true, "line_length": 150},
5+
"MD014": true,
6+
"MD018": true,
7+
"MD022": true,
8+
"MD023": true,
9+
"MD026": { "punctuation": ".,;。，；"},
10+
"MD031": { "list_items": false},
11+
"MD032": true,
12+
"MD035": true,
13+
"MD042": true,
14+
"MD045": true,
15+
"MD052": true
16+
}

‎docs/.sphinx/.wordlist.txt

+64
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
ACME
2+
ACME's
3+
addons
4+
AGPLv
5+
API
6+
APIs
7+
balancer
8+
Charmhub
9+
CLI
10+
DCO
11+
Diátaxis
12+
Dqlite
13+
dropdown
14+
EBS
15+
EKS
16+
enablement
17+
favicon
18+
Furo
19+
Git
20+
GitHub
21+
Grafana
22+
IAM
23+
installable
24+
JSON
25+
Juju
26+
Kubeflow
27+
Kubernetes
28+
Launchpad
29+
linter
30+
LTS
31+
LXD
32+
Makefile
33+
Makefiles
34+
Matrix
35+
Mattermost
36+
MicroCeph
37+
MicroCloud
38+
MicroOVN
39+
MyST
40+
namespace
41+
namespaces
42+
NodePort
43+
Numbat
44+
observability
45+
OEM
46+
OLM
47+
Permalink
48+
pre
49+
Quickstart
50+
ReadMe
51+
reST
52+
reStructuredText
53+
roadmap
54+
RTD
55+
subdirectories
56+
subfolders
57+
subtree
58+
TODO
59+
Ubuntu
60+
UI
61+
UUID
62+
VM
63+
webhook
64+
YAML

‎docs/.sphinx/_static/css/pdf.css

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
/* Only relevant for specific PDF generation issues */
2+
3+
.rubric>.hclass2 {
4+
display: block;
5+
font-size: 2em;
6+
border-radius: .5rem;
7+
font-weight: 300;
8+
line-height: 1.25;
9+
margin-top: 1.75rem;
10+
margin-right: -0.5rem;
11+
margin-bottom: 0.5rem;
12+
margin-left: -0.5rem;
13+
padding-left: .5rem;
14+
padding-right: .5rem;
15+
}

‎docs/.sphinx/_static/favicon.png

2.21 KB
Loading

‎docs/.sphinx/_static/tag.png

6.62 KB
Loading

‎docs/.sphinx/_templates/header.html

+54
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
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+
<!-- NOTE: changed anchor to span until product_page exists -->
9+
<!-- <a class="p-logo" href="https://{{ product_page }}" aria-current="page"> -->
10+
<span class="p-logo" aria-current="page">
11+
<img src="{{ pathto(product_tag,1) }}" alt="Logo" class="p-logo-image">
12+
<div class="p-logo-text p-heading--4">{{ project }}
13+
</div>
14+
</a>
15+
</li>
16+
17+
<li class="nav-ubuntu-com">
18+
<a href="https://{{ product_page }}" class="p-navigation__link">{{ product_page }}</a>
19+
</li>
20+
21+
<li>
22+
<a href="#" class="p-navigation__link nav-more-links">More resources</a>
23+
<ul class="more-links-dropdown">
24+
25+
{% if discourse %}
26+
<li>
27+
<a href="{{ discourse }}" class="p-navigation__sub-link p-dropdown__link">Discourse</a>
28+
</li>
29+
{% endif %}
30+
31+
{% if mattermost %}
32+
<li>
33+
<a href="{{ mattermost }}" class="p-navigation__sub-link p-dropdown__link">Mattermost</a>
34+
</li>
35+
{% endif %}
36+
37+
{% if matrix %}
38+
<li>
39+
<a href="{{ matrix }}" class="p-navigation__sub-link p-dropdown__link">Matrix</a>
40+
</li>
41+
{% endif %}
42+
43+
{% if github_url %}
44+
<li>
45+
<a href="{{ github_url }}" class="p-navigation__sub-link p-dropdown__link">GitHub</a>
46+
</li>
47+
{% endif %}
48+
49+
</ul>
50+
</li>
51+
52+
</ul>
53+
</div>
54+
</header>

0 commit comments

Comments
 (0)