Skip to content

Commit f05b26c

Browse files
a-velascogithub-actions[bot]
a-velasco
and
github-actions[bot]
authored
Refactor v16 documentation for Sphinx (#985)
* add starter pack and sync tutorial with VM * update deployment guides * rename how-to-guides to how-to * sync how-to guides with vm * sync references with vm * sync explanation pages with vm * add .readthedocs.yaml and reduce .gitignore scope for requirements.txt file * fix some formatting issues * sync backup guides with vm * fix misc. build errors and sync tutorial with vm * add doc ci checks * remove discourse sync workflow * polish tutorial and deploy guide * specify channel on all deploy commands * sync misc. pages with vm * minor README update with new documentation link * ignore docs folder in development workflows * remove sphinx python dependency check workflow * update configuration and relevant pages * replace deployment with channel 16 * Update README.md * sync with 16/edge * update ci workflows * update landing page and fix broken reference --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
1 parent 4ce6826 commit f05b26c

File tree

112 files changed

+4194
-2583
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

+4194
-2583
lines changed

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

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
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+
15+
concurrency:
16+
group: ${{ github.workflow }}-${{ github.ref }}
17+
cancel-in-progress: true
18+
19+
jobs:
20+
documentation-checks:
21+
uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main
22+
with:
23+
working-directory: "docs"
24+
fetch-depth: 0

‎.github/workflows/ci.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ on:
1414
- 'LICENSE'
1515
- '**.md'
1616
- .github/renovate.json5
17-
- '.github/workflows/sync_docs.yaml'
17+
- 'docs/**'
1818
schedule:
1919
- cron: '53 0 * * *' # Daily at 00:53 UTC
2020
# Triggered on push to branch "main" by .github/workflows/release.yaml

‎.github/workflows/lib-check.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/markdown-style-checks.yml

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
name: Markdown style checks
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- 'docs/**' # Only run on changes to the docs directory
9+
pull_request:
10+
branches:
11+
- '*'
12+
paths:
13+
- 'docs/**' # Only run on changes to the docs directory
14+
15+
jobs:
16+
markdown-lint:
17+
runs-on: ubuntu-22.04
18+
steps:
19+
- uses: actions/checkout@v4
20+
with:
21+
fetch-depth: 0
22+
- uses: DavidAnson/markdownlint-cli2-action@b4c9feab76d8025d1e83c653fa3990936df0e6c8
23+
with:
24+
config: "docs/.sphinx/.markdownlint.json"

‎.github/workflows/sync_docs.yaml

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

‎.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/16/docs -- '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: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Leave a blank line at the end of this file to support concatenation
2+
backend
3+
backends
4+
Charmcraft
5+
cjk
6+
cryptographically
7+
dvipng
8+
fonts
9+
freefont
10+
github
11+
GPG
12+
gyre
13+
https
14+
Intersphinx
15+
lang
16+
LaTeX
17+
latexmk
18+
Multipass
19+
otf
20+
plantuml
21+
PNG
22+
Pygments
23+
QEMU
24+
Rockcraft
25+
rst
26+
SVG
27+
tex
28+
texlive
29+
TOC
30+
toctree
31+
txt
32+
uncommenting
33+
utils
34+
VMs
35+
WCAG
36+
whitespace
37+
whitespaces
38+
wordlist
39+
xetex
40+
xindy

‎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/.markdownlint.json

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{
2+
"default": false,
3+
"MD003": {
4+
"style": "atx"
5+
},
6+
"MD014": true,
7+
"MD018": true,
8+
"MD022": true,
9+
"MD023": true,
10+
"MD026": {
11+
"punctuation": ".,;。，；"
12+
},
13+
"MD031": {
14+
"list_items": false
15+
},
16+
"MD032": true,
17+
"MD035": true,
18+
"MD042": true,
19+
"MD045": true,
20+
"MD052": true
21+
}

‎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)