Skip to content

Commit 749385a

Browse files
a-velascoa-velasco
authored
Transfer documentation to Read The Docs (#647)
* initial starter pack integration and format conversion * fix sphinx build errors * fix landing pages and toctrees * fix spelling errors * fix broken links * Add CI checks and remove update script * Add password management how-to guide * join all tutorial pages * fix old tutorial references * remove rogue PostgreSQL mentions * polish and sync with VM * Add dedicated troubleshooting guide for specific scenarios * fix broken links * update gitignore to not ignore docs Makefile * fix reference issues * apply review comments
1 parent 9ede90e commit 749385a

File tree

112 files changed

+3485
-2323
lines changed

Some content is hidden

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

112 files changed

+3485
-2323
lines changed

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

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
#
2+
name: Automatic doc checks
3+
4+
on:
5+
push:
6+
branches: [ main ]
7+
pull_request:
8+
paths:
9+
- 'docs/**' # Only run on changes to the docs directory
10+
11+
workflow_dispatch:
12+
# Manual trigger
13+
14+
concurrency:
15+
group: ${{ github.workflow }}-${{ github.ref }}
16+
cancel-in-progress: true
17+
18+
jobs:
19+
documentation-checks:
20+
uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main
21+
with:
22+
working-directory: "docs"
23+
fetch-depth: 0

‎.github/workflows/check_libs.yaml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ on:
1414
- 'LICENSE'
1515
- '**.md'
1616
- 'renovate.json'
17+
- 'docs/**'
1718

1819
jobs:
1920
lib-check:

‎.github/workflows/ci.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ on:
1111
paths-ignore:
1212
- '**.md'
1313
- '.github/renovate.json5'
14-
- '.github/workflows/sync_docs.yaml'
14+
- 'docs/**'
1515
schedule:
1616
- cron: '53 0 * * *' # Daily at 00:53 UTC
1717
# Triggered on push to branch "main" by .github/workflows/release.yaml

‎.github/workflows/release.yaml

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,6 @@ on:
1010
- 'docs/**'
1111
- '.github/renovate.json5'
1212
- '.github/workflows/check_libs.yaml'
13-
- '.github/workflows/sync_docs.yaml'
1413

1514
jobs:
1615
lib-check:

‎.github/workflows/sync_docs.yaml

Lines changed: 0 additions & 18 deletions
This file was deleted.

‎.gitignore

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -140,7 +140,7 @@ build
140140
.config
141141

142142
# Makefile
143-
Makefile
143+
./Makefile
144144

145145
# local pyright settings
146146
pyrightconfig.json

‎.readthedocs.yaml

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
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+
post_checkout:
15+
- git fetch --unshallow || true
16+
# Cancel building pull requests when there aren't changed in the docs directory.
17+
# If there are no changes (git diff exits with 0) we force the command to return with 183.
18+
# This is a special exit code on Read the Docs that will cancel the build immediately.
19+
# https://docs.readthedocs.io/en/stable/build-customization.html#cancel-build-based-on-a-condition
20+
- |
21+
if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- 'docs/' '.readthedocs.yaml';
22+
then
23+
exit 183;
24+
fi
25+
26+
# Build documentation in the docs/ directory with Sphinx
27+
sphinx:
28+
builder: dirhtml
29+
configuration: docs/conf.py
30+
fail_on_warning: true
31+
32+
# If using Sphinx, optionally build your docs in additional formats such as PDF
33+
formats:
34+
- pdf
35+
36+
# Optionally declare the Python requirements required to build your docs
37+
python:
38+
install:
39+
- requirements: docs/requirements.txt

‎docs/.custom_wordlist.txt

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Leave a blank line at the end of this file to support concatenation
2+
airgap
3+
Artifactory
4+
async
5+
backend
6+
backends
7+
backport
8+
Charmcraft
9+
cjk
10+
cryptographically
11+
databag
12+
dvipng
13+
fonts
14+
freefont
15+
Furo
16+
github
17+
GitHub
18+
GPG
19+
gyre
20+
html
21+
https
22+
InnoDB
23+
Intersphinx
24+
io
25+
ip
26+
Jira
27+
landscape
28+
lang
29+
lastmod
30+
LaTeX
31+
latexmk
32+
MinIO
33+
Multipass
34+
mydumper
35+
mysql
36+
MyST
37+
nameserver
38+
nameservers
39+
Open Graph
40+
otf
41+
PDF
42+
Percona
43+
plantuml
44+
PNG
45+
PR
46+
PVC
47+
PVCs
48+
Pygments
49+
pymarkdown
50+
QEMU
51+
Read the Docs
52+
readthedocs
53+
reStructuredText
54+
Rockcraft
55+
rst
56+
sitemapindex
57+
snap_daemon
58+
Sphinx
59+
Spread
60+
spread_test_example
61+
subproject
62+
subprojects
63+
SVG
64+
tex
65+
texlive
66+
TOC
67+
toctree
68+
txt
69+
uncommenting
70+
URL
71+
utils
72+
VMs
73+
WCAG
74+
whitespace
75+
whitespaces
76+
wordlist
77+
xbstream
78+
xetex
79+
xindy
80+
xml
81+
xtrabackup
82+
yaml
83+
YouTube

‎docs/.gitignore

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Environment
2+
*env*/
3+
.sphinx/venv/
4+
5+
# Sphinx
6+
.sphinx/warnings.txt
7+
.sphinx/.wordlist.dic
8+
.sphinx/.doctrees/
9+
.sphinx/update/
10+
.sphinx/node_modules/
11+
12+
# Vale
13+
.sphinx/styles/*
14+
.sphinx/vale.ini
15+
16+
# Build outputs
17+
_build
18+
19+
# Node.js
20+
package*.json
21+
22+
# Unrelated cache and config files
23+
.DS_Store
24+
__pycache__
25+
.idea/
26+
.vscode/

‎docs/.sphinx/.pre-commit-config.yaml

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
repos:
2+
- repo: local
3+
hooks:
4+
- id: make-spelling
5+
name: Run make spelling
6+
entry: make -C docs spelling
7+
language: system
8+
pass_filenames: false
9+
files: ^docs/.*\.(rst|md|txt)$
10+
11+
- id: make-linkcheck
12+
name: Run make linkcheck
13+
entry: make -C docs linkcheck
14+
language: system
15+
pass_filenames: false
16+
files: ^docs/.*\.(rst|md|txt)$
17+
18+
- id: make-woke
19+
name: Run make woke
20+
entry: make -C docs woke
21+
language: system
22+
pass_filenames: false
23+
files: ^docs/.*\.(rst|md|txt)$

0 commit comments

Comments
 (0)