Backport documentation updates to 3df4f0a (v2-edge)

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

@@ -0,0 +1,40 @@
+name: Markdown style checks
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    # Make sure bash is always invoked with `-eo pipefail`
+    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsshell
+    shell: bash
+
+on:
+  workflow_call:
+  push:
+    branches:
+    - main
+    paths:
+    - 'doc/**'   # Only run on changes to the doc directory
+  pull_request:
+    paths:
+    - 'doc/**'   # Only run on changes to the doc directory
+
+jobs:
+  markdown-lint:
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      with:
+        fetch-depth: 0
+        persist-credentials: false
+    - name: Create venv
+      working-directory: "doc"
+      run: make install
+    - name: Lint markdown
+      working-directory: "doc"
+      run: make lint-md

.github/workflows/tests.yml

@@ -297,6 +297,7 @@ jobs:
     with:
       working-directory: './doc'
       makefile: 'Makefile'
+      python-version: '3.12'
 
   snap:
     name: Trigger snap edge build

CONTRIBUTING.md

@@ -5,17 +5,17 @@
 The MicroCloud team welcomes contributions through pull requests, issue reports, and discussions.
 
 - Contribute to the code or documentation, report bugs, or request features in the [GitHub repository](https://github.com/canonical/microcloud).
-- Ask questions or join discussions in the [MicroCloud forum](https://discourse.ubuntu.com/c/lxd/microcloud/145).
+- Ask questions or join discussions in the [MicroCloud forum](https://discourse.ubuntu.com/c/project/lxd/microcloud/145).
 
 Review the following guidelines before contributing to the project.
 
 ## Code of Conduct
 
-All contributors must adhere to the [Ubuntu Code of Conduct](https://ubuntu.com/community/ethos/code-of-conduct).
+All contributors must adhere to the [Ubuntu Code of Conduct](https://ubuntu.com/community/docs/ethos/code-of-conduct).
 
 ## License and copyright
 
-All external contributors must sign the [Canonical contributor license agreement (CCLA)](https://ubuntu.com/legal/contributors), which grants Canonical permission to use the contributions.
+All external contributors must sign the [Canonical contributor license agreement (CCLA)](https://canonical.com/legal/contributors), which grants Canonical permission to use the contributions.
 
 - You retain copyright ownership of your contributions (no copyright assignment).
 - By default, contributions are licensed under the project's **AGPL-3.0-only** license.

doc/.custom_wordlist.txt

@@ -69,6 +69,7 @@ scalable
 SDN
 snapd
 SSD
+subfolders
 subnet
 subnets
 SVG

doc/.gitignore

@@ -1,8 +1,6 @@
 /*env*/
-.sphinx/venv/
-.sphinx/requirements.txt
+.venv/
 .sphinx/warnings.txt
-.sphinx/.wordlist.dic
 .sphinx/.doctrees/
 .sphinx/node_modules/
 package*.json

doc/.readthedocs.yaml

@@ -15,12 +15,7 @@ build:
       - git fetch --unshallow || true
       - cd doc && make GOTOOLCHAIN=auto integrate
       - cd doc/integration/lxd/ && GOTOOLCHAIN=auto go build -ldflags "-s -w" -o trimpath -o lxc.bin ./lxc
-      # Pretend that woke is installed - we don't need it for building
-      # (workaround until https://github.com/canonical/microovn/pull/168 is merged
-      # and https://github.com/canonical/microceph/pull/400 is restored)
-      - ln -s /bin/true doc/integration/microovn/docs/woke
-      - ln -s /bin/true doc/integration/microceph/docs/woke
-      - make GOTOOLCHAIN=auto doc-html-rtd PATH=$PATH:.
+      - cd doc && make GOTOOLCHAIN=auto html-rtd PATH=$PATH:.
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
@@ -35,4 +30,4 @@ sphinx:
 # Optionally declare the Python requirements required to build your docs
 python:
    install:
-   - requirements: doc/.sphinx/requirements.txt
+   - requirements: doc/requirements.txt

doc/.sphinx/.pymarkdown.json

@@ -0,0 +1,39 @@
+{
+    "plugins": {
+        "selectively_enable_rules": true,
+        "heading-style": {
+            "enabled": true,
+            "style": "atx"
+        },
+        "commands-show-output": {
+            "enabled": true
+        },
+        "no-missing-space-atx": {
+            "enabled": true
+        },
+        "heading-start-left": {
+            "enabled": true
+        },
+        "no-trailing-punctuation": {
+            "enabled": true,
+            "punctuation": ".,;。،；"
+        },
+        "blanks-around-lists": {
+            "enabled": true
+        },
+        "hr-style": {
+            "enabled": true
+        },
+        "no-empty-links": {
+            "enabled": true
+        },
+        "no-alt-text": {
+            "enabled": true
+        }
+    },
+    "extensions": {
+        "front-matter" : {
+            "enabled" : true
+        }
+    }
+}

doc/.sphinx/_integration/add_config.py

@@ -11,22 +11,18 @@
 
 if project == "LXD":
     html_baseurl = "https://documentation.ubuntu.com/lxd/stable-5.21/"
-    html_js_files.append('rtd-search.js')
     html_css_files = globals().get('html_css_files', []) + ['override-header.css']
     tags.add('integrated')
 elif project == "MicroCeph":
-    html_baseurl = "https://canonical-microceph.readthedocs-hosted.com/en/latest/"
+    html_baseurl = "https://documentation.ubuntu.com/canonical-microceph/v19.2.0-squid/"
     # Override default header templates
-    templates_path = globals().get('templates_path', []) + [".sphinx/_templates"]
+    templates_path = globals().get('templates_path', []) + ["_templates"]
     # Override default header styles
-    html_static_path = globals().get('html_static_path', []) + [".sphinx/_static"]
+    html_static_path = globals().get('html_static_path', []) + ["_static"]
     html_css_files = globals().get('html_css_files', []) + ['override-header.css']
-    # Add rtd-search.js to the list of JS files
-    html_js_files = globals().get('html_js_files', []) + ['rtd-search.js']
     # Add "integrated" to the list of custom tags
-    custom_tags = globals().get('custom_tags', []) + ['integrated']
+    tags.add('integrated')
 elif project == "MicroOVN":
     html_baseurl = "https://canonical-microovn.readthedocs-hosted.com/en/24.03/"
-    custom_html_js_files.append('rtd-search.js')
     custom_tags.append('integrated')