Skip to content

Commit e667f95

Browse files
izmalkizmalk
authored
[DPE-9337] docs: Bootstrap docs for Cassandra (#45)
* Bootstrap docs for Cassandra * Remove redundant OpenAPI config * Remove PDF generation * Fix Markdown linter * Fix link checker error
1 parent ce3d170 commit e667f95

21 files changed

+1470
-9
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_call:
12+
workflow_dispatch:
13+
# Manual trigger
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/check-removed-urls.yml‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
name: Check for removed URLs
2+
3+
on:
4+
workflow_call:
5+
pull_request:
6+
branches: [main]
7+
paths:
8+
- 'docs/**'
9+
10+
jobs:
11+
build-docs:
12+
runs-on: ubuntu-latest
13+
steps:
14+
- name: Checkout PR branch
15+
uses: actions/checkout@v5
16+
with:
17+
# This implicitly gets the PR branch. Making it explicit causes problems
18+
# with private forks, but it is equivalent to the following:
19+
# repository: ${{ github.event.pull_request.head.repo.full_name }}
20+
# ref: ${{ github.event.pull_request.head.ref }}
21+
fetch-depth: 0
22+
path: compare
23+
- name: Checkout base branch
24+
uses: actions/checkout@v5
25+
with:
26+
ref: ${{ github.event.pull_request.base.ref }}
27+
repository: ${{ github.event.pull_request.base.repo.full_name }}
28+
fetch-depth: 0
29+
path: base
30+
- uses: actions/setup-python@v6
31+
- name: Build docs
32+
run: |
33+
for dir in compare base; do
34+
pushd ${dir}/docs
35+
make install
36+
. .sphinx/venv/bin/activate
37+
make html
38+
popd
39+
done
40+
- name: Generate current URLs list
41+
run: |
42+
for dir in compare base; do
43+
pushd ${dir}/docs
44+
find ./_build/ -name '*.html' \
45+
| sed 's|/_build||;s|/index.html$|/|;s|.html$||' \
46+
| sort > urls.txt
47+
popd
48+
done
49+
- name: Compare URLs
50+
run: |
51+
BASE_URLS_PATH="base/docs/urls.txt"
52+
COMPARE_URLS_PATH="compare/docs/urls.txt"
53+
removed=$(comm -23 ${BASE_URLS_PATH} ${COMPARE_URLS_PATH} )
54+
if [ -n "$removed" ]; then
55+
echo "The following URLs were removed:"
56+
echo "$removed"
57+
echo "Please ensure removed pages are redirected"
58+
exit 1
59+
fi

‎.github/workflows/cla-check.yml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# This workflow checks if the contributor has signed the Canonical Contributor Licence Agreement (CLA)
2+
name: Canonical Contributor Licence Agreement check
3+
4+
on:
5+
pull_request:
6+
branches: [main]
7+
8+
jobs:
9+
cla-check:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- name: Check if CLA signed
13+
uses: canonical/has-signed-canonical-cla@v2

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

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
name: Markdown style checks
2+
3+
on:
4+
workflow_call:
5+
push:
6+
branches:
7+
- main
8+
paths:
9+
- 'docs/**' # Only run on changes to the docs directory
10+
pull_request:
11+
branches:
12+
- '*'
13+
paths:
14+
- 'docs/**' # Only run on changes to the docs directory
15+
16+
jobs:
17+
markdown-lint:
18+
runs-on: ubuntu-22.04
19+
steps:
20+
- uses: actions/checkout@v5
21+
with:
22+
fetch-depth: 0
23+
- name: Create venv
24+
working-directory: "docs"
25+
run: make install
26+
- name: Lint markdown
27+
working-directory: "docs"
28+
run: make lint-md

‎.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: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Leave a blank line at the end of this file to support concatenation
2+
backend
3+
backends
4+
Canonical('s)?
5+
Charmcraft
6+
cjk
7+
cryptographically
8+
dvipng
9+
fonts
10+
freefont
11+
github
12+
GPG
13+
gyre
14+
https
15+
html
16+
io
17+
Intersphinx
18+
lang
19+
LaTeX
20+
latexmk
21+
Multipass
22+
otf
23+
plantuml
24+
PNG
25+
Pygments
26+
pymarkdown
27+
QEMU
28+
Rockcraft
29+
readthedocs
30+
redeclare
31+
rst
32+
sitemapindex
33+
subproject
34+
subprojects
35+
SCons
36+
SVG
37+
tex
38+
texlive
39+
TOC
40+
toctree
41+
txt
42+
uncomment(ing)?
43+
utils
44+
uv
45+
VMs
46+
WCAG
47+
whitespace
48+
whitespaces
49+
wordlist
50+
xetex
51+
xindy
52+
xml
53+
ip
54+
spread_test_example
55+
Furo
56+
PDF
57+
Open Graph
58+
MyST
59+
YouTube
60+
reStructuredText
61+
GitHub
62+
Sphinx
63+
URL
64+
PR
65+
Read the Docs
66+
Spread
67+
landscape
68+
lastmod
69+
yaml
70+
sequenceDiagram
71+
Numpy
72+
openapi
73+
docstrings?
74+
Makefile
75+
retrigger(ing)?

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

‎docs/.sphinx/.pymarkdown.json‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
{
2+
"plugins": {
3+
"selectively_enable_rules": true,
4+
"heading-style": {
5+
"enabled": true,
6+
"style": "atx"
7+
},
8+
"commands-show-output": {
9+
"enabled": true
10+
},
11+
"no-missing-space-atx": {
12+
"enabled": true
13+
},
14+
"blanks-around-headings": {
15+
"enabled": true
16+
},
17+
"heading-start-left": {
18+
"enabled": true
19+
},
20+
"no-trailing-punctuation": {
21+
"enabled": true,
22+
"punctuation": ".,;。，；"
23+
},
24+
"blanks-around-fences": {
25+
"enabled": true,
26+
"list_items": false
27+
},
28+
"blanks-around-lists": {
29+
"enabled": true
30+
},
31+
"hr-style": {
32+
"enabled": true
33+
},
34+
"no-empty-links": {
35+
"enabled": true
36+
},
37+
"no-alt-text": {
38+
"enabled": true
39+
}
40+
},
41+
"extensions": {
42+
"front-matter" : {
43+
"enabled" : true
44+
}
45+
}
46+
}

0 commit comments

Comments
 (0)