"
+ @echo "-------------------------------------------------------------"
+ @echo
+
+.PHONY: help full-help html epub linkcheck spelling spellcheck woke \
+ vale pa11y run serve install pa11y-install \
+ vale-install clean clean-doc lint-md lint \
+ integrate clean-integrate html html-rtd microcloud \
+ serve-microcloud pymarkdownlnt-install
+
+full-help: $(DOCS_VENVDIR)
+ @. $(DOCS_VENV); $(SPHINX_BUILD) -M help "$(DOCS_SOURCEDIR)" "$(DOCS_BUILDDIR)" $(SPHINX_OPTS) $(O)
+ @echo "\n\033[1;31mNOTE: This help texts shows unsupported targets!\033[0m"
+ @echo "Run 'make help' to see supported targets."
+
+# If requirements are updated, venv should be rebuilt and timestamped.
+$(DOCS_VENVDIR):
+ @echo "... setting up virtualenv"
+ python3 -m venv $(DOCS_VENVDIR) || { echo "You must install python3-venv before you can build the documentation."; exit 1; }
+ . $(DOCS_VENV); pip install $(PIPOPTS) --require-virtualenv \
+ --upgrade -r requirements.txt \
+ --log $(DOCS_VENVDIR)/pip_install.log
+ @test ! -f $(DOCS_VENVDIR)/pip_list.txt || \
+ mv $(DOCS_VENVDIR)/pip_list.txt $(DOCS_VENVDIR)/pip_list.txt.bak
+ @. $(DOCS_VENV); pip list --local --format=freeze > $(DOCS_VENVDIR)/pip_list.txt
+ @touch $(DOCS_VENVDIR)
+
+pa11y-install:
+ @command -v $(PA11Y_CMD) >/dev/null || { \
+ echo "Installing \"pa11y\" from npm..."; echo; \
+ mkdir -p $(SPHINX_DIR)/node_modules/ ; \
+ npm install --prefix $(SPHINX_DIR) pa11y; \
+ }
+
+pymarkdownlnt-install: install
+ @. $(DOCS_VENV); test -d $(DOCS_VENVDIR)/lib/python*/site-packages/pymarkdown || pip install pymarkdownlnt==0.9.35
+
+install: $(DOCS_VENVDIR)
+
+run: install
+ . $(DOCS_VENV); $(DOCS_VENVDIR)/bin/sphinx-autobuild -b dirhtml --host $(SPHINX_HOST) --port $(SPHINX_PORT) "$(DOCS_SOURCEDIR)" "$(DOCS_BUILDDIR)" $(SPHINX_OPTS)
integrate:
# Pull the other repositories
@@ -44,76 +91,143 @@ integrate:
cd integration/ && ( git -C microovn fetch || git clone https://github.com/canonical/microovn )
git -C integration/microovn reset --hard $(MICROOVNVERSION)
+
# Create a directory for files to override in MicroCloud docs
mkdir -p integration/microcloud/_templates/ integration/microcloud/_static
- mkdir -p integration/microceph/docs/.sphinx/_templates integration/microceph/docs/.sphinx/_static
+ mkdir -p integration/microceph/docs/_templates integration/microceph/docs/_static
+
# Copy the header HTML and CSS files for the doc sets
cp .sphinx/_integration/microcloud.html integration/microcloud/_templates/header.html
- cp .sphinx/_integration/header.css integration/microcloud/_static/
+ cp .sphinx/_integration/override-header.css integration/microcloud/_static/
cp .sphinx/_integration/lxd.html integration/lxd/doc/_templates/header.html
cp .sphinx/_integration/override-header.css integration/lxd/doc/_static/
- cp .sphinx/_integration/microceph.html integration/microceph/docs/.sphinx/_templates/header.html
- cp .sphinx/_integration/override-header.css integration/microceph/docs/.sphinx/_static/
+ cp .sphinx/_integration/microceph.html integration/microceph/docs/_templates/header.html
+ cp .sphinx/_integration/override-header.css integration/microceph/docs/_static/
cp .sphinx/_integration/microovn.html integration/microovn/docs/.sphinx/_templates/header.html
cp .sphinx/_integration/header.css integration/microovn/docs/.sphinx/_static/
- # Copy the search JavaScript file
- cp .sphinx/_integration/rtd-search.js integration/microcloud/_static/
- cp .sphinx/_integration/rtd-search.js integration/lxd/doc/_static/
- cp .sphinx/_integration/rtd-search.js integration/microceph/docs/.sphinx/_static/
- cp .sphinx/_integration/rtd-search.js integration/microovn/docs/.sphinx/_static/
+
# Add information about where to find the tags/docs to the doc sets
cat .sphinx/_integration/add_config.py >> integration/lxd/doc/conf.py
cat .sphinx/_integration/add_config.py >> integration/microceph/docs/conf.py
cat .sphinx/_integration/add_config.py >> integration/microovn/docs/custom_conf.py
+
# Override the MicroOVN tag with the circle of friends one (for consistency)
cp .sphinx/_integration/tag.png integration/microovn/docs/.sphinx/_static/microovn.png
-clean-integrate:
- rm -rf integration/lxd
- rm -rf integration/microceph
- rm -rf integration/microovn
-
-clean: clean-integrate
- $(MAKE) -f Makefile.sp sp-clean
-
# `html` builds the integrated docs.
-html: integrate
+html: integrate install
mkdir -p $(current_dir)/_build
cd integration/lxd/doc/ && $(MAKE) html BUILDDIR=$(current_dir)/_build/lxd
cd integration/microceph/docs/ && $(MAKE) html BUILDDIR=$(current_dir)/_build/microceph
cd integration/microovn/docs/ && $(MAKE) html BUILDDIR=$(current_dir)/_build/microovn
- $(MAKE) -f Makefile.sp sp-html BUILDDIR=$(current_dir)/_build ADDPREREQS='gitpython pyyaml'
+ . $(DOCS_VENV); $(SPHINX_BUILD) -W --keep-going -b dirhtml "$(DOCS_SOURCEDIR)" "$(current_dir)/_build" -w $(SPHINX_DIR)/warnings.txt $(SPHINX_OPTS)
# `html-rtd` builds the integrated docs, with the correct paths for Read the Docs.
# This target is used by the Read the Docs build.
-html-rtd:
+html-rtd: install
PATH_PREFIX=$(PATH_PREFIX) $(MAKE) -C integration/lxd/doc/ html-rtd BUILDDIR=$(READTHEDOCS_OUTPUT)/html/lxd
PATH_PREFIX=$(PATH_PREFIX) $(MAKE) -C integration/microceph/docs/ html BUILDDIR=$(READTHEDOCS_OUTPUT)/html/microceph
PATH_PREFIX=$(PATH_PREFIX) $(MAKE) -C integration/microovn/docs/ html BUILDDIR=$(READTHEDOCS_OUTPUT)/html/microovn
- ADDPREREQS='gitpython pyyaml' PATH_PREFIX=$(PATH_PREFIX) $(MAKE) -f Makefile.sp sp-html BUILDDIR=$(READTHEDOCS_OUTPUT)/html
+ . $(DOCS_VENV); PATH_PREFIX=$(PATH_PREFIX) $(SPHINX_BUILD) -W --keep-going -b dirhtml "$(DOCS_SOURCEDIR)" "$(READTHEDOCS_OUTPUT)/html" -w $(SPHINX_DIR)/warnings.txt $(SPHINX_OPTS)
-# `spelling` checks only the MicroCloud docs.
-spelling: clean-doc microcloud
- $(MAKE) -f Makefile.sp sp-spellcheck
+epub: install
+ . $(DOCS_VENV); $(SPHINX_BUILD) -b epub "$(DOCS_SOURCEDIR)" "$(DOCS_BUILDDIR)" -w $(SPHINX_DIR)/warnings.txt $(SPHINX_OPTS)
# `microcloud` builds only the MicroCloud docs, as a stand-alone doc set.
-microcloud:
- $(MAKE) -f Makefile.sp sp-html SINGLE_BUILD=True
-
-.PHONY: run
-run:
- $(MAKE) -f Makefile.sp sp-run LOCAL_SPHINX_BUILD=True ADDPREREQS='gitpython pyyaml' SPHINXOPTS="--ignore './index.html' -c . -d .sphinx/.doctrees -j auto"
+microcloud: install
+ . $(DOCS_VENV); SINGLE_BUILD=True $(SPHINX_BUILD) -W --keep-going -b dirhtml "$(DOCS_SOURCEDIR)" "$(DOCS_BUILDDIR)" -w $(SPHINX_DIR)/warnings.txt $(SPHINX_OPTS)
# `serve` rebuilds the integrated docs and serves them.
serve: html
- cd $(current_dir)/_build/; python3 -m http.server --bind 127.0.0.1 8000
+ cd "$(DOCS_BUILDDIR)"; python3 -m http.server --bind $(SPHINX_HOST) $(SPHINX_PORT)
-# `serve-microcloud` rebuilds the MicroCloud docs as a stand-along doc set and serves them.
+# `serve-microcloud` rebuilds the MicroCloud docs as a stand-alone doc set and serves them.
serve-microcloud: microcloud
- cd $(current_dir)/_build/; python3 -m http.server --bind 127.0.0.1 8000
-
-install:
- $(MAKE) -f Makefile.sp sp-install ADDPREREQS='pyyaml'
+ cd "$(DOCS_BUILDDIR)"; python3 -m http.server --bind $(SPHINX_HOST) $(SPHINX_PORT)
+
+clean: clean-integrate clean-doc
+ @test ! -e "$(DOCS_VENVDIR)" -o -d "$(DOCS_VENVDIR)" -a "$(abspath $(DOCS_VENVDIR))" != "$(DOCS_VENVDIR)"
+ rm -rf $(DOCS_VENVDIR)
+ rm -rf $(SPHINX_DIR)/node_modules/
+ rm -rf $(SPHINX_DIR)/styles
+ rm -rf $(VALE_CONFIG)
+
+clean-doc:
+ git clean -fx "$(DOCS_BUILDDIR)"
+ rm -rf $(SPHINX_DIR)/.doctrees
+clean-integrate:
+ rm -rf integration/lxd
+ rm -rf integration/microceph
+ rm -rf integration/microcloud
+ rm -rf integration/microovn
+
+linkcheck: install
+ . $(DOCS_VENV) ; SINGLE_BUILD=True $(SPHINX_BUILD) -b linkcheck -q "$(DOCS_SOURCEDIR)" "$(DOCS_BUILDDIR)" $(SPHINX_OPTS) || { grep --color -F "[broken]" "$(DOCS_BUILDDIR)/output.txt"; exit 1; }
+ exit 0
+
+pa11y: pa11y-install html
+ find $(DOCS_BUILDDIR) -name *.html -print0 | xargs -n 1 -0 $(PA11Y_CMD)
+
+# Without --return-code-scheme explicit, pymarkdownlnt returns 1 for multiple scenarios
+# By using the explicit scheme, it only returns 1 when no files are found,
+# which should not result in failure
+lint lint-md: pymarkdownlnt-install
+ @echo "Running Markdown linting..."
+ @. $(DOCS_VENV); pymarkdownlnt \
+ --config $(SPHINX_DIR)/.pymarkdown.json \
+ --return-code-scheme explicit \
+ scan \
+ --recurse \
+ --exclude=$(SPHINX_DIR)/** \
+ --exclude=$(DOCS_VENVDIR)/** \
+ --exclude=$(INTEGRATION_DIR)/** \
+ $(DOCS_SOURCEDIR); \
+ status=$$?; \
+ if [ $$status -eq 1 ]; then \
+ echo "No Markdown files selected for linting"; \
+ echo "Passed"; \
+ exit 0; \
+ elif [ $$status -ne 0 ]; then \
+ echo "Failed"; \
+ exit $$status; \
+ else \
+ echo "Passed"; \
+ fi;
+
+vale-install: install
+ @. $(DOCS_VENV); test -f $(VALE_CONFIG) || python3 $(SPHINX_DIR)/get_vale_conf.py
+ @echo '.Name=="Canonical.400-Enforce-inclusive-terms"' > $(SPHINX_DIR)/styles/woke.filter
+ @echo '.Level=="error" and .Name!="Canonical.500-Repeated-words" and .Name!="Canonical.000-US-spellcheck"' > $(SPHINX_DIR)/styles/error.filter
+ @echo '.Name=="Canonical.000-US-spellcheck"' > $(SPHINX_DIR)/styles/spelling.filter
+ @. $(DOCS_VENV); find $(VALE_DIR)/vale_bin -size 195c -exec vale --version \;
+
+woke: vale-install
+ @cat $(DOCS_VOCAB)/accept.txt > $(DOCS_VOCAB)/accept_backup.txt
+ @cat $(DOCS_SOURCEDIR)/.custom_wordlist.txt >> $(DOCS_VOCAB)/accept.txt
+ @echo "Running Vale acceptable term check against $(CHECK_PATH). To change target set CHECK_PATH= with make command"
+ @. $(DOCS_VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINX_DIR)/styles/woke.filter' --glob='*.{md,rst}' $(CHECK_PATH)
+ @cat $(DOCS_VOCAB)/accept_backup.txt > $(DOCS_VOCAB)/accept.txt && rm $(DOCS_VOCAB)/accept_backup.txt
+
+vale: vale-install
+ @cat $(DOCS_VOCAB)/accept.txt > $(DOCS_VOCAB)/accept_backup.txt
+ @cat $(DOCS_SOURCEDIR)/.custom_wordlist.txt >> $(DOCS_VOCAB)/accept.txt
+ @echo "Running Vale against $(CHECK_PATH). To change target set CHECK_PATH= with make command"
+ @. $(DOCS_VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINX_DIR)/styles/error.filter' --glob='*.{md,rst}' $(CHECK_PATH)
+ @cat $(DOCS_VOCAB)/accept_backup.txt > $(DOCS_VOCAB)/accept.txt && rm $(DOCS_VOCAB)/accept_backup.txt
+
+spelling: vale-install
+ @cat $(DOCS_VOCAB)/accept.txt > $(DOCS_VOCAB)/accept_backup.txt
+ @cat $(DOCS_SOURCEDIR)/.custom_wordlist.txt >> $(DOCS_VOCAB)/accept.txt
+ @echo "Running Vale against $(CHECK_PATH). To change target set CHECK_PATH= with make command"
+ @. $(DOCS_VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINX_DIR)/styles/spelling.filter' --glob='*.{md,rst}' $(CHECK_PATH)
+ @cat $(DOCS_VOCAB)/accept_backup.txt > $(DOCS_VOCAB)/accept.txt && rm $(DOCS_VOCAB)/accept_backup.txt
+
+spellcheck: spelling
+ @echo "Please note that the \`make spellcheck\` command is being deprecated in favor of \`make spelling\`"
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option. $(O) is meant as a shortcut for $(SPHINX_OPTS).
%:
- $(MAKE) -f Makefile.sp sp-$@
+ $(MAKE) --no-print-directory install
+ . $(DOCS_VENV); $(SPHINX_BUILD) -M $@ "$(DOCS_SOURCEDIR)" "$(DOCS_BUILDDIR)" $(SPHINX_OPTS) $(O)
diff --git a/doc/Makefile.sp b/doc/Makefile.sp
deleted file mode 100644
index 61c42cf82..000000000
--- a/doc/Makefile.sp
+++ /dev/null
@@ -1,121 +0,0 @@
-# Minimal makefile for Sphinx documentation
-#
-# `Makefile.sp` is from the Sphinx starter pack and should not be
-# modified.
-# Add your customisation to `Makefile` instead.
-
-# You can set these variables from the command line, and also
-# from the environment for the first two.
-SPHINXDIR = .sphinx
-SPHINXOPTS ?= -c . -d $(SPHINXDIR)/.doctrees -j auto
-SPHINXBUILD ?= sphinx-build
-SOURCEDIR = .
-BUILDDIR = _build
-VENVDIR = $(SPHINXDIR)/venv
-PA11Y = $(SPHINXDIR)/node_modules/pa11y/bin/pa11y.js --config $(SPHINXDIR)/pa11y.json
-VENV = $(VENVDIR)/bin/activate
-TARGET = *
-ALLFILES = *.rst **/*.rst
-ADDPREREQS ?=
-
-.PHONY: sp-full-help sp-woke-install sp-pa11y-install sp-install sp-run sp-html \
- sp-epub sp-serve sp-clean sp-clean-doc sp-spelling sp-spellcheck sp-linkcheck sp-woke \
- sp-pa11y Makefile.sp sp-vale
-
-sp-full-help: $(VENVDIR)
- @. $(VENV); $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
- @echo "\n\033[1;31mNOTE: This help texts shows unsupported targets!\033[0m"
- @echo "Run 'make help' to see supported targets."
-
-# Shouldn't assume that venv is available on Ubuntu by default; discussion here:
-# https://bugs.launchpad.net/ubuntu/+source/python3.4/+bug/1290847
-$(SPHINXDIR)/requirements.txt:
- @python3 -c "import venv" || \
- (echo "You must install python3-venv before you can build the documentation."; exit 1)
- python3 -m venv $(VENVDIR)
- @if [ ! -z "$(ADDPREREQS)" ]; then \
- . $(VENV); pip install --require-virtualenv $(ADDPREREQS); \
- fi
- . $(VENV); python3 $(SPHINXDIR)/build_requirements.py
-
-# If requirements are updated, venv should be rebuilt and timestamped.
-$(VENVDIR): $(SPHINXDIR)/requirements.txt
- @echo "... setting up virtualenv"
- python3 -m venv $(VENVDIR)
- . $(VENV); pip install --require-virtualenv \
- --upgrade -r $(SPHINXDIR)/requirements.txt \
- --log $(VENVDIR)/pip_install.log
- @test ! -f $(VENVDIR)/pip_list.txt || \
- mv $(VENVDIR)/pip_list.txt $(VENVDIR)/pip_list.txt.bak
- @. $(VENV); pip list --local --format=freeze > $(VENVDIR)/pip_list.txt
- @touch $(VENVDIR)
-
-sp-woke-install:
- @type woke >/dev/null 2>&1 || \
- { echo "Installing \"woke\" snap... \n"; sudo snap install woke; }
-
-sp-pa11y-install:
- @type $(PA11Y) >/dev/null 2>&1 || { \
- echo "Installing \"pa11y\" from npm... \n"; \
- mkdir -p $(SPHINXDIR)/node_modules/ ; \
- npm install --prefix $(SPHINXDIR) pa11y; \
- }
-
-sp-install: $(VENVDIR)
-
-sp-run: sp-install
- . $(VENV); sphinx-autobuild -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
-
-# Doesn't depend on $(BUILDDIR) to rebuild properly at every run.
-sp-html: sp-install
- . $(VENV); $(SPHINXBUILD) -W --keep-going -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS)
-
-sp-epub: sp-install
- . $(VENV); $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS)
-
-sp-serve: sp-html
- cd "$(BUILDDIR)"; python3 -m http.server --bind 127.0.0.1 8000
-
-sp-clean: sp-clean-doc
- @test ! -e "$(VENVDIR)" -o -d "$(VENVDIR)" -a "$(abspath $(VENVDIR))" != "$(VENVDIR)"
- rm -rf $(VENVDIR)
- rm -f $(SPHINXDIR)/requirements.txt
- rm -rf $(SPHINXDIR)/node_modules/
- rm -rf $(SPHINXDIR)/styles
- rm -rf $(SPHINXDIR)/vale.ini
-
-sp-clean-doc:
- git clean -fx "$(BUILDDIR)"
- rm -rf $(SPHINXDIR)/.doctrees
-
-sp-spellcheck:
- . $(VENV) ; python3 -m pyspelling -c $(SPHINXDIR)/spellingcheck.yaml -j $(shell nproc)
-
-sp-spelling: sp-html sp-spellcheck
-
-sp-linkcheck: sp-install
- . $(VENV) ; $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) || { grep --color -F "[broken]" "$(BUILDDIR)/output.txt"; exit 1; }
- exit 0
-
-sp-woke: sp-woke-install
- woke $(ALLFILES) --exit-1-on-failure \
- -c https://github.com/canonical/Inclusive-naming/raw/main/config.yml
-
-sp-pa11y: sp-pa11y-install sp-html
- find $(BUILDDIR) -name *.html -print0 | xargs -n 1 -0 $(PA11Y)
-
-sp-vale: sp-install
- @. $(VENV); test -d $(SPHINXDIR)/venv/lib/python*/site-packages/vale || pip install vale
- @. $(VENV); test -f $(SPHINXDIR)/vale.ini || python3 $(SPHINXDIR)/get_vale_conf.py
- @. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --config "$(SPHINXDIR)/vale.ini" $(TARGET) > /dev/null \;
- @echo ""
- @echo "Running Vale against $(TARGET). To change target set TARGET= with make command"
- @echo ""
- @. $(VENV); vale --config "$(SPHINXDIR)/vale.ini" --glob='*.{md,txt,rst}' $(TARGET)
-
-
-
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile.sp
- . $(VENV); $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/doc/.sphinx/_static/favicon.png b/doc/_static/favicon.png
similarity index 100%
rename from doc/.sphinx/_static/favicon.png
rename to doc/_static/favicon.png
diff --git a/doc/.sphinx/_static/tag.png b/doc/_static/microcloud_tag.png
similarity index 100%
rename from doc/.sphinx/_static/tag.png
rename to doc/_static/microcloud_tag.png
diff --git a/doc/.sphinx/_templates/base.html b/doc/_templates/base.html
similarity index 100%
rename from doc/.sphinx/_templates/base.html
rename to doc/_templates/base.html
diff --git a/doc/.sphinx/_templates/footer.html b/doc/_templates/footer.html
similarity index 53%
rename from doc/.sphinx/_templates/footer.html
rename to doc/_templates/footer.html
index 577478c95..242f91ab3 100644
--- a/doc/.sphinx/_templates/footer.html
+++ b/doc/_templates/footer.html
@@ -5,7 +5,7 @@
{% if meta %}
{% if 'sequential_nav' in meta %}
{% set sequential_nav = meta.sequential_nav %}
- {% endif %}
+ {% endif %}
{% endif %}
{# mod: Conditional wrappers to control page navigation buttons #}
{% if sequential_nav != "none" -%}
@@ -43,15 +43,26 @@
{%- if hasdoc('copyright') %}
{% trans path=pathto('copyright'), copyright=copyright|e -%}
-
Copyright © {{ copyright }}
+
© {{ copyright }} {{ author }}
{%- endtrans %}
{%- else %}
{% trans copyright=copyright|e -%}
- Copyright © {{ copyright }}
+ © {{ copyright }} {{ author }}
{%- endtrans %}
{%- endif %}
+ This page is licensed under {{ license.name }}
+
+ {%- endif -%}
+ {%- endif -%}
{# mod: removed "Made with" #}
@@ -70,65 +81,8 @@
{%- endif %}
-
- {% if github_url and github_folder and pagename and page_source_suffix and display_contributors %}
- {% set contributors = get_contribs(github_url, github_folder, pagename, page_source_suffix, display_contributors_since) %}
- {% if contributors %}
- {% if contributors | length > 1 %}
-
Thanks to the {{ contributors |length }} contributors!
- {% else %}
-
Thanks to our contributor!
- {% endif %}
-
-
- {% endif %}
- {% endif %}
-
-
- {# mod: replaced RTD icons with our links #}
-
- {% if discourse %}
-
- {% endif %}
-
- {% if mattermost %}
-
- {% endif %}
-
- {% if matrix %}
-
- {% endif %}
-
- {% if github_url and github_version and github_folder %}
-
- {% if github_issues %}
-
- {% endif %}
-
-
- {% endif %}
-
{# mod: Added link to manage cookie tracker settings #}
-
-
-
Sorry, but the documentation page that you are looking for was not found.
\n\nDocumentation changes over time, and pages are moved around. We try to redirect you to the updated content where possible, but unfortunately, that didn\'t work this time (maybe because the content you were looking for does not exist in this version of the documentation).
\nYou can try to use the navigation to locate the content you\'re looking for, or search for a similar page.
\n',
+ 'sequential_nav': 'both',
}
-# Default image for OGP (to prevent font errors, see
-# https://github.com/canonical/sphinx-docs-starter-pack/pull/54 )
-if not 'ogp_image' in locals():
- ogp_image = 'https://assets.ubuntu.com/v1/253da317-image-document-ubuntudocs.svg'
+# Enables the pencil icon to edit pages on GitHub, shown at the top of each page
+html_theme_options = {
+ 'source_edit_link': html_context['github_url']
+}
-############################################################
-### General configuration
-############################################################
+# Project slug
+# Required if your project is hosted on documentation.ubuntu.com
+slug = 'microcloud'
+
+#######################
+# Sitemap configuration: https://sphinx-sitemap.readthedocs.io/
+#######################
+
+# sphinx-sitemap uses html_baseurl (set earlier in this file) to generate the full URL for each page:
+
+sitemap_url_scheme = '{link}'
+
+# Include `lastmod` dates in the sitemap:
+sitemap_show_lastmod = True
+
+# Exclude generated pages from the sitemap:
+sitemap_excludes = [
+ '404/',
+ 'genindex/',
+ 'search/',
+]
+
+# Add more pages to sitemap_excludes if needed. Wildcards are supported.
+# For example, to exclude module pages generated by autodoc, add '_modules/*'.
+
+#######################
+# Template and asset locations
+#######################
+
+html_static_path = ['_static']
+
+
+#############
+# Redirects #
+#############
+
+# Add redirects to the 'redirects.txt' file
+# https://sphinxext-rediraffe.readthedocs.io/en/latest/
+
+# To set up redirects in the Read the Docs project dashboard:
+# https://docs.readthedocs.io/en/stable/guides/redirects.html
+
+rediraffe_redirects = 'redirects.txt'
+
+# Strips '/index.html' from destination URLs when building with 'dirhtml'
+rediraffe_dir_only = True
+
+###########################
+# Link checker exceptions #
+###########################
+# Always ignore these links
+linkcheck_ignore = [
+ 'http://127.0.0.1:8000',
+ 'http://localhost:8000',
+ # These links may fail from time to time
+ 'https://ceph.io',
+ # Cloudflare protection on SourceForge domains often block linkcheck
+ r'https://.*\.sourceforge\.(net|io)/.*',
+ # These links often fail due to infra issues or protection measures
+ r'https://ubuntu\.com.*',
+ # Ignore so that we can link change log in release notes before a release is ready
+ r'https://github\.com/canonical/microcloud/compare.*',
+]
+
+# Pages on which to ignore anchors (check the link without the anchor)
+linkcheck_anchors_ignore_for_url = [
+ r'https://snapcraft\.io/docs/.*',
+ r'https://github\.com/.*',
+ r'https://charmhub\.io/.*',
+]
+
+# Increase linkcheck rate limit timeout max, default when unset is 300
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-linkcheck_timeout
+linkcheck_rate_limit_timeout = 600
+
+# Increase linkcheck retries, default when unset is 1
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-linkcheck_retries
+linkcheck_retries = 3
+
+# Increase the duration, in seconds, that the linkcheck builder will wait for a response after each hyperlink request.
+# Default when unset is 30
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-linkcheck_timeout
+linkcheck_timeout = 45
+
+
+########################
+# Configuration extras #
+########################
+
+extensions = [
+ 'canonical_sphinx',
+ 'notfound.extension',
+ 'sphinx_design',
+ 'sphinx_rerediraffe',
+ 'sphinx_tabs.tabs',
+ 'sphinxcontrib.jquery',
+ 'sphinxext.opengraph',
+ 'sphinx_related_links',
+ 'sphinx_roles',
+ 'sphinx_terminal',
+ 'sphinx_youtube_links',
+ 'sphinxcontrib.cairosvgconverter',
+ 'sphinx_last_updated_by_git',
+ 'sphinx.ext.intersphinx',
+ 'sphinx_sitemap',
+ 'myst_parser',
+]
+
+# Excludes files or directories from processing
exclude_patterns = [
'_build',
'Thumbs.db',
'.DS_Store',
'.sphinx',
+ '.venv',
+ 'reference/release-notes/release-notes-template.md',
+ 'integration',
+ 'README.md',
]
-exclude_patterns.extend(custom_excludes)
-
-rst_epilog = '''
-.. include:: /reuse/links.txt
-'''
-if 'custom_rst_epilog' in locals():
- rst_epilog = custom_rst_epilog
-source_suffix = {
- '.rst': 'restructuredtext',
- '.md': 'markdown',
-}
+html_css_files = [
+ 'https://assets.ubuntu.com/v1/d86746ef-cookie_banner.css',
+]
-if not 'conf_py_path' in html_context and 'github_folder' in html_context:
- html_context['conf_py_path'] = html_context['github_folder']
+if os.environ.get('SINGLE_BUILD') != 'True':
+ html_css_files.append('override-header.css')
-# For ignoring specific links
-linkcheck_anchors_ignore_for_url = [
- r'https://github\.com/.*'
+html_js_files = [
+ 'https://assets.ubuntu.com/v1/287a5e8f-bundle.js',
+ 'rtd-versions-flyout.js',
]
-linkcheck_anchors_ignore_for_url.extend(custom_linkcheck_anchors_ignore_for_url)
-# Tags cannot be added directly in custom_conf.py, so add them here
-for tag in custom_tags:
- tags.add(tag)
+# Feedback button at the top; enabled by default
+# To disable the button, uncomment the line below:
+
+# disable_feedback_button = True
+
+# Define a :center: role that can be used to center the content of table cells.
+rst_prolog = '''
+.. role:: center
+ :class: align-center
+.. role:: h2
+ :class: hclass2
+.. role:: woke-ignore
+ :class: woke-ignore
+.. role:: vale-ignore
+ :class: vale-ignore
+'''
-# html_context['get_contribs'] is a function and cannot be
-# cached (see https://github.com/sphinx-doc/sphinx/issues/12300)
-suppress_warnings = ["config.cache"]
+# Load substitutions from YAML file
+if os.path.exists('./reuse/substitutions.yaml'):
+ with open('./reuse/substitutions.yaml', 'r') as fd:
+ myst_substitutions = yaml.safe_load(fd.read())
############################################################
### Styling
@@ -141,77 +241,63 @@
# Setting templates_path for epub makes the build fail
if builder == 'dirhtml' or builder == 'html':
- templates_path = ['.sphinx/_templates']
- if 'custom_templates_path' in globals():
- templates_path = custom_templates_path + templates_path
+ templates_path = ['_templates']
+ if os.environ.get('SINGLE_BUILD') != 'True':
+ templates_path.insert(0, 'integration/microcloud/_templates')
notfound_template = '404.html'
-# Theme configuration
-html_theme = 'furo'
-html_last_updated_fmt = ''
-html_permalinks_icon = '¶'
+##########################################
+### Misc MicroCloud custom configuration #
+##########################################
+
+# Use custom 404 page text
+notfound_context = {
+ 'title': 'Page not found',
+ 'body': 'Sorry, but the documentation page that you are looking for was not found.
\n\nDocumentation changes over time, and pages are moved around. We try to redirect you to the updated content where possible, but unfortunately, that didn\'t work this time (maybe because the content you were looking for does not exist in this version of the documentation).
\nYou can try to use the navigation to locate the content you\'re looking for, or search for a similar page.
\n',
+}
-if html_title == '':
- html_theme_options = {
- 'sidebar_hide_name': True
- }
+# Intersphinx setup differs for different builds to optimize use with integrated docs
+if ('SINGLE_BUILD' in os.environ and os.environ['SINGLE_BUILD'] == 'True'):
+ intersphinx_mapping = {
+ 'lxd': ('https://documentation.ubuntu.com/lxd/stable-5.21/', None),
+ 'microceph': ('https://documentation.ubuntu.com/canonical-microceph/v19.2.0-squid/', None),
+ 'microovn': ('https://canonical-microovn.readthedocs-hosted.com/en/24.03/', None),
+ }
+elif ('READTHEDOCS' in os.environ) and (os.environ['READTHEDOCS'] == 'True'):
+ intersphinx_mapping = {
+ 'lxd': (os.environ['PATH_PREFIX'] + 'lxd/', os.environ['READTHEDOCS_OUTPUT'] + 'html/lxd/objects.inv'),
+ 'microceph': (os.environ['PATH_PREFIX'] + 'microceph/', os.environ['READTHEDOCS_OUTPUT'] + 'html/microceph/objects.inv'),
+ 'microovn': (os.environ['PATH_PREFIX'] + 'microovn/', os.environ['READTHEDOCS_OUTPUT'] + 'html/microovn/objects.inv'),
+ }
+else:
+ intersphinx_mapping = {
+ 'lxd': ('/lxd/', '_build/lxd/objects.inv'),
+ 'microceph': ('/microceph/', '_build/microceph/objects.inv'),
+ 'microovn': ('/microovn/', '_build/microovn/objects.inv'),
+ }
-############################################################
-### Additional files
-############################################################
+# Add intersphinx mappings for docs sets not part of the MicroCloud integrated docs here:
-html_static_path = ['.sphinx/_static']
-if 'custom_html_static_path' in globals():
- html_static_path = html_static_path + custom_html_static_path
+base_intersphinx = {
+ 'ceph': ('https://docs.ceph.com/en/latest/', None),
+ 'snap': ('https://snapcraft.io/docs/', None),
+}
-html_css_files = [
- 'custom.css',
- 'header.css',
- 'github_issue_links.css',
- 'furo_colors.css',
- 'footer.css'
-]
-html_css_files.extend(custom_html_css_files)
-
-html_js_files = ['header-nav.js', 'footer.js']
-if 'github_issues' in html_context and html_context['github_issues'] and not disable_feedback_button:
- html_js_files.append('github_issue_links.js')
-html_js_files.extend(custom_html_js_files)
-
-#############################################################
-# Display the contributors
-
-def get_contributors_for_file(github_url, github_folder, pagename, page_source_suffix, display_contributors_since=None):
- filename = f"{pagename}{page_source_suffix}"
- paths=html_context['github_folder'][1:] + filename
-
- try:
- repo = Repo(".")
- except InvalidGitRepositoryError:
- cwd = os.getcwd()
- ghfolder = html_context['github_folder'][:-1]
- if ghfolder and cwd.endswith(ghfolder):
- repo = Repo(cwd.rpartition(ghfolder)[0])
- else:
- print("The local Git repository could not be found.")
- return
-
- since = display_contributors_since if display_contributors_since and display_contributors_since.strip() else None
-
- commits = repo.iter_commits(paths=paths, since=since)
-
- contributors_dict = {}
- for commit in commits:
- contributor = commit.author.name
- if contributor not in contributors_dict or commit.committed_date > contributors_dict[contributor]['date']:
- contributors_dict[contributor] = {
- 'date': commit.committed_date,
- 'sha': commit.hexsha
- }
- # The github_page contains the link to the contributor's latest commit.
- contributors_list = [{'name': name, 'github_page': f"{github_url}/commit/{data['sha']}"} for name, data in contributors_dict.items()]
- sorted_contributors_list = sorted(contributors_list, key=lambda x: x['name'])
- return sorted_contributors_list
-
-html_context['get_contribs'] = get_contributors_for_file
-#############################################################
+intersphinx_mapping.update(base_intersphinx)
+
+# Update html_context for integrated builds and add the "integrated" tag
+if os.environ.get('SINGLE_BUILD') != 'True':
+ exec(compile(source=open('.sphinx/_integration/add_config.py').read(), filename='.sphinx/_integration/add_config.py', mode='exec'))
+ # MicroCloud docs are at the URL root, so override the relative paths to sibling doc sets
+ html_context['lxd_path'] = 'lxd'
+ html_context['lxd_tag'] = 'lxd/_static/lxd_tag.png'
+ html_context['microceph_path'] = 'microceph'
+ html_context['microceph_tag'] = 'microceph/_static/tag.png'
+ html_context['microovn_path'] = 'microovn'
+ html_context['microovn_tag'] = 'microovn/_static/microovn.png'
+ html_static_path.append('integration/microcloud/_static')
+ tags.add('integrated')
+
+# Version label shown in the RTD flyout next to "default", in parentheses.
+# Set the FLYOUT_DEFAULT_VERSION_LABEL environment variable in the RTD project dashboard.
+html_context['flyout_default_version_label'] = os.environ.get('FLYOUT_DEFAULT_VERSION_LABEL', '')
diff --git a/doc/custom_conf.py b/doc/custom_conf.py
deleted file mode 100644
index 7a4518901..000000000
--- a/doc/custom_conf.py
+++ /dev/null
@@ -1,331 +0,0 @@
-import datetime
-import os
-import re
-import yaml
-from redirects import redirects
-
-# Custom configuration for the Sphinx documentation builder.
-# All configuration specific to your project should be done in this file.
-#
-# The file is included in the common conf.py configuration file.
-# You can modify any of the settings below or add any configuration that
-# is not covered by the common conf.py file.
-#
-# For the full list of built-in configuration values, see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
-#
-# If you're not familiar with Sphinx and don't want to use advanced
-# features, it is sufficient to update the settings in the "Project
-# information" section.
-
-############################################################
-### Project information
-############################################################
-
-# Product name
-project = 'MicroCloud'
-author = 'Canonical Group Ltd'
-
-with open('../version/version.go') as f:
- match = re.search(r'RawVersion = "([^"]+)"', f.read())
- version = match.group(1) if match else ''
-
-# Sidebar documentation title; best kept reasonably short
-# To disable the title, set to an empty string.
-html_title = project + ' documentation ' + version
-
-# The default value uses the current year as the copyright year.
-#
-# For static works, it is common to provide the year of first publication.
-# Another option is to give the first year and the current year
-# for documentation that is often changed, e.g. 2022–2023 (note the en-dash).
-#
-# A way to check a GitHub repo's creation date is to obtain a classic GitHub
-# token with 'repo' permissions here: https://github.com/settings/tokens
-# Next, use 'curl' and 'jq' to extract the date from the GitHub API's output:
-#
-# curl -H 'Authorization: token ' \
-# -H 'Accept: application/vnd.github.v3.raw' \
-# https://api.github.com/repos/canonical/ | jq '.created_at'
-
-copyright = '%s, %s' % (datetime.date.today().year, author)
-
-## Open Graph configuration - defines what is displayed as a link preview
-## when linking to the documentation from another website (see https://ogp.me/)
-# The URL where the documentation will be hosted (leave empty if you
-# don't know yet)
-# NOTE: If no ogp_* variable is defined (e.g. if you remove this section) the
-# sphinxext.opengraph extension will be disabled.
-ogp_site_url = 'https://documentation.ubuntu.com/microcloud/'
-# The documentation website name (usually the same as the product name)
-ogp_site_name = project
-# The URL of an image or logo that is used in the preview
-ogp_image = 'https://assets.ubuntu.com/v1/d53eeeac-Microcloud_favicon_64px_v2.png'
-
-# Update with the local path to the favicon for your product
-# (default is the circle of friends)
-html_favicon = '.sphinx/_static/favicon.png'
-
-# (Some settings must be part of the html_context dictionary, while others
-# are on root level. Don't move the settings.)
-html_context = {
-
- # Change to the link to the website of your product (without "https://")
- # For example: "ubuntu.com/lxd" or "microcloud.is"
- # If there is no product website, edit the header template to remove the
- # link (see the readme for instructions).
- 'product_page': 'canonical.com/microcloud',
-
- # Add your product tag (the orange part of your logo, will be used in the
- # header) to ".sphinx/_static" and change the path here (start with "_static")
- # (default is the circle of friends)
- 'product_tag': '_static/tag.png',
-
- # Change to the discourse instance you want to be able to link to
- # using the :discourse: metadata at the top of a file
- # (use an empty value if you don't want to link)
- 'discourse': 'https://discourse.ubuntu.com/c/lxd/microcloud/',
-
- # ru-fu: we're using different Discourses
- 'discourse_prefix': {
- 'ubuntu': 'https://discourse.ubuntu.com/t/',
- 'lxc': 'https://discuss.linuxcontainers.org/t/',
- },
-
- # Change to the Mattermost channel you want to link to
- # (use an empty value if you don't want to link)
- 'mattermost': '',
-
- # Change to the Matrix channel you want to link to
- # (use an empty value if you don't want to link)
- 'matrix': '',
-
- # Change to the GitHub URL for your project
- # This is used, for example, to link to the source files and allow creating GitHub issues directly from the documentation.
- 'github_url': 'https://github.com/canonical/microcloud',
-
- # Change to the branch for this version of the documentation
- 'github_version': 'main',
-
- # Change to the folder that contains the documentation
- # (usually "/" or "/docs/")
- 'github_folder': '/doc/',
-
- # Change to an empty value if your GitHub repo doesn't have issues enabled.
- # This will disable the feedback button and the issue link in the footer.
- 'github_issues': 'enabled',
-
- # Controls the existence of Previous / Next buttons at the bottom of pages
- # Valid options: none, prev, next, both
- 'sequential_nav': "both",
-
- # Controls if to display the contributors of a file or not
- "display_contributors": True,
-
- # Controls time frame for showing the contributors
- "display_contributors_since": ""
-}
-
-# If your project is on documentation.ubuntu.com, specify the project
-# slug (for example, "lxd") here.
-slug = "microcloud"
-
-#######################
-# Sitemap configuration: https://sphinx-sitemap.readthedocs.io/
-#######################
-
-# Base URL of RTD hosted project
-
-html_baseurl = 'https://documentation.ubuntu.com/microcloud/'
-
-# Configures URL scheme for sphinx-sitemap to generate correct URLs
-# based on the version if built in RTD
-if 'READTHEDOCS_VERSION' in os.environ:
- rtd_version = os.environ["READTHEDOCS_VERSION"]
- sitemap_url_scheme = f'{rtd_version}/{{link}}'
-else:
- sitemap_url_scheme = '{link}'
-
-############################################################
-### Redirects
-############################################################
-
-# Set up redirects (https://documatt.gitlab.io/sphinx-reredirects/usage.html)
-# For example: 'explanation/old-name.html': '../how-to/prettify.html',
-# You can also configure redirects in the Read the Docs project dashboard
-# (see https://docs.readthedocs.io/en/stable/guides/redirects.html).
-# NOTE: If this variable is not defined, set to None, or the dictionary is empty,
-# the sphinx_reredirects extension will be disabled.
-# minae: Redirects is imported from redirects.py
-
-############################################################
-### Link checker
-############################################################
-
-# Links to ignore when checking links
-linkcheck_ignore = [
- 'http://127.0.0.1:8000',
- 'http://localhost:8000',
- # These links may fail from time to time
- 'https://ceph.io',
- # Cloudflare protection on SourceForge domains often block linkcheck
- r"https://.*\.sourceforge\.(net|io)/.*",
- # Ignore so that we can link change log in release notes before a release is ready
- r"https://github\.com/canonical/microcloud/compare.*",
- ]
-
-# Pages on which to ignore anchors
-# (This list will be appended to linkcheck_anchors_ignore_for_url)
-
-custom_linkcheck_anchors_ignore_for_url = [
- r'https://snapcraft\.io/docs/.*'
- ]
-
-# Increase linkcheck rate limit timeout max, default when unset is 300
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-linkcheck_timeout
-linkcheck_rate_limit_timeout = 600
-
-# Increase linkcheck retries, default when unset is 1
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-linkcheck_retries
-linkcheck_retries = 3
-
-# Increase the duration, in seconds, that the linkcheck builder will wait for a response after each hyperlink request.
-# Default when unset is 30
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-linkcheck_timeout
-linkcheck_timeout = 45
-
-############################################################
-### Additions to default configuration
-############################################################
-
-## The following settings are appended to the default configuration.
-## Use them to extend the default functionality.
-
-# Remove this variable to disable the MyST parser extensions.
-custom_myst_extensions = []
-
-# Add custom Sphinx extensions as needed.
-# This array contains recommended extensions that should be used.
-# NOTE: The following extensions are handled automatically and do
-# not need to be added here: myst_parser, sphinx_copybutton, sphinx_design,
-# sphinx_reredirects, sphinxcontrib.jquery, sphinxext.opengraph
-custom_extensions = [
- 'sphinx_tabs.tabs',
- 'canonical.youtube-links',
- 'canonical.related-links',
- 'canonical.custom-rst-roles',
- 'canonical.terminal-output',
- 'notfound.extension',
- 'sphinx.ext.intersphinx',
- 'sphinx_sitemap',
- ]
-
-# Add custom required Python modules that must be added to the
-# .sphinx/requirements.txt file.
-# NOTE: The following modules are handled automatically and do not need to be
-# added here: canonical-sphinx-extensions, furo, linkify-it-py, myst-parser,
-# pyspelling, sphinx, sphinx-autobuild, sphinx-copybutton, sphinx-design,
-# sphinx-notfound-page, sphinx-reredirects, sphinx-tabs, sphinxcontrib-jquery,
-# sphinxext-opengraph
-custom_required_modules = [
- 'sphinx-sitemap',
- 'pyyaml',
-]
-
-# Add files or directories that should be excluded from processing.
-custom_excludes = [
- "integration",
- 'README.md'
- ]
-
-# Add CSS files (located in .sphinx/_static/ or from external link)
-custom_html_css_files = [
- 'https://assets.ubuntu.com/v1/d86746ef-cookie_banner.css',
-]
-
-# Add JavaScript files (located in .sphinx/_static/ or from external link)
-custom_html_js_files = [
- 'https://assets.ubuntu.com/v1/287a5e8f-bundle.js',
- 'rtd-versions-flyout.js',
-]
-
-## The following settings override the default configuration.
-
-# Specify a reST string that is included at the end of each file.
-# If commented out, use the default (which pulls the reuse/links.txt
-# file into each reST file).
-# custom_rst_epilog = ''
-
-# By default, the documentation includes a feedback button at the top.
-# You can disable it by setting the following configuration to True.
-disable_feedback_button = False
-
-# Add tags that you want to use for conditional inclusion of text
-# (https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#tags)
-custom_tags = []
-
-# If you are using the :manpage: role, set this variable to the URL for the version
-# that you want to link to:
-# manpages_url = "https://manpages.ubuntu.com/manpages/noble/en/man{section}/{page}.{section}.html"
-
-############################################################
-### Additional configuration
-############################################################
-
-## Add any configuration that is not covered by the common conf.py file.
-
-if ('SINGLE_BUILD' in os.environ and os.environ['SINGLE_BUILD'] == 'True'):
- intersphinx_mapping = {
- 'lxd': ('https://documentation.ubuntu.com/lxd/stable-5.21/', None),
- 'microceph': ('https://canonical-microceph.readthedocs-hosted.com/en/v19.2.0-squid/', None),
- 'microovn': ('https://documentation.ubuntu.com/microcloud/v2/microovn/', None),
- }
-elif ('READTHEDOCS' in os.environ) and (os.environ['READTHEDOCS'] == 'True'):
- intersphinx_mapping = {
- 'lxd': (os.environ['PATH_PREFIX'] + 'lxd/', os.environ['READTHEDOCS_OUTPUT'] + 'html/lxd/objects.inv'),
- 'microceph': (os.environ['PATH_PREFIX'] + 'microceph/', os.environ['READTHEDOCS_OUTPUT'] + 'html/microceph/objects.inv'),
- 'microovn': (os.environ['PATH_PREFIX'] + 'microovn/', os.environ['READTHEDOCS_OUTPUT'] + 'html/microovn/objects.inv'),
- }
-else:
- intersphinx_mapping = {
- 'lxd': ('/lxd/', '_build/lxd/objects.inv'),
- 'microceph': ('/microceph/', '_build/microceph/objects.inv'),
- 'microovn': ('/microovn/', '_build/microovn/objects.inv'),
- }
-
-# Add intersphinx mappings for docs sets not part of the MicroCloud integrated docs here:
-
-base_intersphinx = {
- 'ceph': ('https://docs.ceph.com/en/latest/', None),
- 'snap': ('https://snapcraft.io/docs/', None),
-}
-
-intersphinx_mapping.update(base_intersphinx)
-
-# Define a :center: role that can be used to center the content of table cells.
-rst_prolog = '''
-.. role:: center
- :class: align-center
-'''
-
-if not ('SINGLE_BUILD' in os.environ and os.environ['SINGLE_BUILD'] == 'True'):
- exec(compile(source=open('.sphinx/_integration/add_config.py').read(), filename='.sphinx/_integration/add_config.py', mode='exec'))
- # MicroCloud docs are at the URL root, so override the relative paths to sibling doc sets
- html_context['lxd_path'] = "lxd"
- html_context['lxd_tag'] = "lxd/_static/tag.png"
- html_context['microceph_path'] = "microceph"
- html_context['microceph_tag'] = "microceph/_static/tag.png"
- html_context['microovn_path'] = "microovn"
- html_context['microovn_tag'] = "microovn/_static/microovn.png"
- custom_html_static_path = ['integration/microcloud/_static']
- custom_templates_path = ['integration/microcloud/_templates']
- custom_tags.append('integrated')
-
-# Load substitutions from YAML file
-if os.path.exists('./substitutions.yaml'):
- with open('./substitutions.yaml', 'r') as fd:
- myst_substitutions = yaml.safe_load(fd.read())
-
-# Version label shown in the RTD flyout next to "default", in parentheses.
-# Set the FLYOUT_DEFAULT_VERSION_LABEL environment variable in the RTD project dashboard.
-html_context['flyout_default_version_label'] = os.environ.get('FLYOUT_DEFAULT_VERSION_LABEL', '')
diff --git a/doc/doc-cheat-sheet-myst.md b/doc/doc-cheat-sheet-myst.md
deleted file mode 100644
index 5662a7397..000000000
--- a/doc/doc-cheat-sheet-myst.md
+++ /dev/null
@@ -1,256 +0,0 @@
----
-orphan: true
-myst:
- substitutions:
- reuse_key: "This is **included** text."
- advanced_reuse_key: "This is a substitution that includes a code block:
- ```
- code block
- ```"
----
-
-
-
-(cheat-sheet-myst)=
-# Markdown/MyST cheat sheet
-
-
-
-This file contains the syntax for commonly used Markdown and MyST markup.
-Open it in your text editor to quickly copy and paste the markup you need.
-
-See the [MyST syntax guide](https://canonical-starter-pack.readthedocs-hosted.com/stable/reference/myst-syntax-reference/) for detailed information and conventions.
-
-Also see the [MyST documentation](https://myst-parser.readthedocs.io/en/latest/index.html) for detailed information on MyST, and the [Canonical Documentation Style Guide](https://docs.ubuntu.com/styleguide/en) for general style conventions.
-
-## H2 heading
-
-### H3 heading
-
-#### H4 heading
-
-##### H5 heading
-
-## Inline formatting
-
-- {guilabel}`UI element`
-- `code`
-- {command}`command`
-- {kbd}`Key`
-- *Italic*
-- **Bold**
-
-## Code blocks
-
-Start a code block:
-
- code:
- - example: true
-
-```
-# Demonstrate a code block
-code:
- - example: true
-```
-
-```yaml
-# Demonstrate a code block
-code:
- - example: true
-```
-
-(a_section_target_myst)=
-## Links
-
-- [Canonical website](https://canonical.com/)
-- {ref}`a_section_target_myst`
-- {ref}`Link text `
-- {doc}`index`
-- {doc}`Link text `
-
-## Navigation
-
-Use the following syntax::
-
- ```{toctree}
- :hidden:
-
- sub-page1
- sub-page2
- ```
-
-## Lists
-
-1. Step 1
- - Item 1
- * Sub-item
- - Item 2
- 1. Sub-step 1
- 1. Sub-step 2
-1. Step 2
- 1. Sub-step 1
- - Item
- 1. Sub-step 2
-
-Term 1
-: Definition
-
-Term 2
-: Definition
-
-## Tables
-
-## Markdown tables
-
-| Header 1 | Header 2 |
-|------------------------------------|----------|
-| Cell 1
Second paragraph | Cell 2 |
-| Cell 3 | Cell 4 |
-
-Centered:
-
-| Header 1 | Header 2 |
-|:----------------------------------:|:--------:|
-| Cell 1
Second paragraph | Cell 2 |
-| Cell 3 | Cell 4 |
-
-## List tables
-
-```{list-table}
- :header-rows: 1
-
-* - Header 1
- - Header 2
-* - Cell 1
-
- Second paragraph
- - Cell 2
-* - Cell 3
- - Cell 4
-```
-
-Centered:
-
-```{list-table}
- :header-rows: 1
- :align: center
-
-* - Header 1
- - Header 2
-* - Cell 1
-
- Second paragraph
- - Cell 2
-* - Cell 3
- - Cell 4
-```
-
-## Notes
-
-```{note}
-A note.
-```
-
-```{tip}
-A tip.
-```
-
-```{important}
-Important information
-```
-
-```{caution}
-This might damage your hardware!
-```
-
-## Images
-
-
-
-```{figure} https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png
- :width: 100px
- :alt: Alt text
-
- Figure caption
-```
-
-## Reuse
-
-### Keys
-
-Keys can be defined at the top of a file, or in a `myst_substitutions` option in `conf.py`.
-
-{{reuse_key}}
-
-{{advanced_reuse_key}}
-
-### File inclusion
-
-## Tabs
-
-````{tabs}
-```{group-tab} Tab 1
-
-Content Tab 1
-```
-
-```{group-tab} Tab 2
-Content Tab 2
-```
-````
-
-## Glossary
-
-```{glossary}
-
-some term
- Definition of the example term.
-```
-
-{term}`some term`
-
-## More useful markup
-
-- ```{versionadded} X.Y
-- {abbr}`API (Application Programming Interface)`
-
-----
-
-## Custom extensions
-
-Related links at the top of the page (surrounded by `---`):
-
- relatedlinks: https://github.com/canonical/lxd-sphinx-extensions, [RTFM](https://www.google.com)
- discourse: 12345
-
-Terms that should not be checked by the spelling checker: {spellexception}`PurposelyWrong`
-
-A single-line terminal view that separates input from output:
-
-```{terminal}
- :input: command
- :user: root
- :host: vampyr
- :dir: /home/user/directory/
-
-the output
-```
-
-A multi-line version of the same:
-
-```{terminal}
- :user: root
- :host: vampyr
- :dir: /home/user/directory/
-
-:input: command 1
-output 1
-:input: command 2
-output 2
-```
-
-A link to a YouTube video:
-
-```{youtube} https://www.youtube.com/watch?v=iMLiK1fX4I0
- :title: Demo
-```
diff --git a/doc/explanation/initialization.md b/doc/explanation/initialization.md
index 377049322..967f460f5 100644
--- a/doc/explanation/initialization.md
+++ b/doc/explanation/initialization.md
@@ -45,9 +45,9 @@ The bootstrapping process consists of the following steps:
After the initialization is complete, you can look at the LXD configuration to confirm the setup.
```{terminal}
-:input: lxc cluster list
:host: micro01
:scroll:
+lxc cluster list
+---------+------------------------------------+-----------------+--------------+----------------+-------------+--------+-------------------+
| NAME | URL | ROLES | ARCHITECTURE | FAILURE DOMAIN | DESCRIPTION | STATE | MESSAGE |
@@ -59,7 +59,13 @@ After the initialization is complete, you can look at the LXD configuration to c
+---------+------------------------------------+-----------------+--------------+----------------+-------------+--------+-------------------+
| micro03 | https://[2001:db8:d:100::171]:8443 | database | aarch64 | default | | ONLINE | Fully operational |
+---------+------------------------------------+-----------------+--------------+----------------+-------------+--------+-------------------+
-:input: lxc storage list
+```
+
+```{terminal}
+:host: micro01
+:scroll:
+lxc storage list
+
+-----------+--------+--------------------------------------------+---------+---------+
| NAME | DRIVER | DESCRIPTION | USED BY | STATE |
+-----------+--------+--------------------------------------------+---------+---------+
@@ -69,7 +75,13 @@ After the initialization is complete, you can look at the LXD configuration to c
+-----------+--------+--------------------------------------------+---------+---------+
| remote-fs | cephfs | Distributed file-system storage using Ceph | 7 | CREATED |
+-----------+--------+--------------------------------------------+---------+---------+
-:input: lxc network list
+```
+
+```{terminal}
+:host: micro01
+:scroll:
+lxc network list
+
+----------+----------+---------+-----------------+---------------------------+-------------+---------+---------+
| NAME | TYPE | MANAGED | IPV4 | IPV6 | DESCRIPTION | USED BY | STATE |
+----------+----------+---------+-----------------+---------------------------+-------------+---------+---------+
@@ -81,7 +93,13 @@ After the initialization is complete, you can look at the LXD configuration to c
+----------+----------+---------+-----------------+---------------------------+-------------+---------+---------+
| eth0.200 | vlan | NO | | | | 1 | |
+----------+----------+---------+-----------------+---------------------------+-------------+---------+---------+
-:input: lxc profile show default
+```
+
+```{terminal}
+:host: micro01
+:scroll:
+lxc profile show default
+
config: {}
description: ""
devices:
diff --git a/doc/explanation/security.md b/doc/explanation/security.md
index 64a638ff1..8ab18e742 100644
--- a/doc/explanation/security.md
+++ b/doc/explanation/security.md
@@ -31,7 +31,7 @@ Report potential security issues privately through GitHub by [filing a security
MicroCloud manages cluster membership and encrypted communication through mTLS and certificate-based identities. When a machine joins a cluster, it verifies the cluster’s certificate fingerprint and receives the complete set of member certificates, establishing a consistent trust store.
-During the join process, MicroCloud uses an **explicit trust establishment mechanism** designed to prevent secret leakage and mitigate man-in-the-middle attacks. This mechanism uses a Hash-Based Message Authentication Code (HMAC) to sign the messages exchanged between the machine that initiates the join process and the joining peers. The shared secret used for joining is never transmitted over the network. The join process also enforces rate limits and session timeouts to reduce the risk of replay and brute-force attacks. For further information, refer to the [public specification](https://discourse.ubuntu.com/t/explicit-trust-establishment-mechanism-for-microcloud/44261).
+During the join process, MicroCloud uses an **explicit trust establishment mechanism** designed to prevent secret leakage and mitigate {spellexception}`man-in-the-middle` attacks. This mechanism uses a Hash-Based Message Authentication Code (HMAC) to sign the messages exchanged between the machine that initiates the join process and the joining peers. The shared secret used for joining is never transmitted over the network. The join process also enforces rate limits and session timeouts to reduce the risk of replay and brute-force attacks. For further information, refer to the [public specification](https://discourse.ubuntu.com/t/explicit-trust-establishment-mechanism-for-microcloud/44261).
(exp-security-lxd)=
## LXD
diff --git a/doc/how-to/ceph_networking.md b/doc/how-to/ceph_networking.md
index a082097ec..a988ca772 100644
--- a/doc/how-to/ceph_networking.md
+++ b/doc/how-to/ceph_networking.md
@@ -111,10 +111,10 @@ The following instructions build on our {ref}`multi-member tutorial micro1.48746: Flags [P.], seq 329386555:329422755, ack 245889462, win 24576, options [nop,nop,TS val 3552095031 ecr 3647909539], length 36200
17:48:48.601012 IP micro1.48746 > 10.0.1.4.6804: Flags [.], ack 329386555, win 24317, options [nop,nop,TS val 3647909564 ecr 3552095031], length 0
diff --git a/doc/how-to/contribute.md b/doc/how-to/contribute.md
index 13cc00b49..321a41d16 100644
--- a/doc/how-to/contribute.md
+++ b/doc/how-to/contribute.md
@@ -30,7 +30,7 @@ Clarify concepts or common questions based on your own experience.
Report documentation issues by opening an issue in [GitHub](https://github.com/canonical/microcloud/issues).
: - We will evaluate and update the documentation as needed.
-Ask questions or suggest improvements in the [MicroCloud forum](https://discourse.ubuntu.com/c/lxd/microcloud/145).
+Ask questions or suggest improvements in the [MicroCloud forum](https://discourse.ubuntu.com/c/project/lxd/microcloud/145).
: - We monitor discussions and update the documentation when necessary.
If you contribute images to `doc/images`:
@@ -39,11 +39,12 @@ If you contribute images to `doc/images`:
### Documentation framework
-The MicroCloud documentation and its integrated documentation sets are built with [Sphinx](https://www.sphinx-doc.org/) and hosted on [Read the Docs](https://about.readthedocs.com/). For structuring, all use the [Diátaxis](https://diataxis.fr/) approach.
+The MicroCloud documentation and its integrated documentation sets are built with [Sphinx](https://www.sphinx-doc.org/en/master/) and hosted on [Read the Docs](https://about.readthedocs.com/). The documentation structure follows the [Diátaxis](https://diataxis.fr/) framework.
-The MicroCloud and LXD documentation sets are written in [Markdown](https://commonmark.org/) with [MyST](https://myst-parser.readthedocs.io/) extensions. For syntax help and guidelines, see the [MyST style guide](https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide-myst/) and the [documentation cheat sheet](cheat-sheet-myst) ([source](https://raw.githubusercontent.com/canonical/microcloud/main/doc/doc-cheat-sheet-myst.md)).
-
-The MicroCeph and MicroOVN documentation sets are written in a documentation markup language called [reStructuredText](https://docutils.sourceforge.io/rst.html) (`.rst`). Differences in functionality are few; however, syntax differs.
+The MicroCloud and LXD documentation sets are written in [Markdown](https://commonmark.org/) with [MyST](https://myst-parser.readthedocs.io/en/latest/) extensions.
+The MicroCeph and MicroOVN documentation sets are written in a documentation markup language called [reStructuredText](https://docutils.sourceforge.io/rst.html) (`.rst`).
+Differences in functionality are few; however, syntax differs.
+For syntax help and guidelines, see the guides to [MyST syntax](https://documentation.ubuntu.com/sphinx-stack/latest/reference/myst-syntax/) and [reStructuredText syntax](https://documentation.ubuntu.com/sphinx-stack/latest/reference/rst-syntax/) in the [Sphinx Stack documentation](https://documentation.ubuntu.com/sphinx-stack/latest/).
### Build the documentation
diff --git a/doc/how-to/install.md b/doc/how-to/install.md
index 6a3f2fa77..c0573b4d5 100644
--- a/doc/how-to/install.md
+++ b/doc/how-to/install.md
@@ -88,6 +88,11 @@ For detailed information, refer to {ref}`reference-requirements`.
Install all required {ref}`snaps ` on each machine intended as a MicroCloud cluster member. Enter the following commands on all machines:
+```{admonition} Snap channels
+:class: note
+The snap channels shown below install the current {ref}`LTS release ` of MicroCloud, along with the most recent compatible releases for its components. To install the {ref}`current feature release ` of MicroCloud instead, refer to the [install guide for that version](https://documentation.ubuntu.com/microcloud/latest/how-to/install/).
+```
+
```bash
sudo snap install lxd --channel=5.21/stable --cohort="+"
sudo snap install microceph --channel=squid/stable --cohort="+"
diff --git a/doc/how-to/member_remove.md b/doc/how-to/member_remove.md
index 52e6dee5b..72128ea4f 100644
--- a/doc/how-to/member_remove.md
+++ b/doc/how-to/member_remove.md
@@ -33,7 +33,7 @@ Removing a cluster member with `--force` will not attempt to perform any clean-u
## Reducing the cluster to one member
-When shrinking the cluster down to one member, you must also clean up the Ceph monmap before proceeding, even when using the `--force` flag.
+When shrinking the cluster down to one member, you must also clean up the Ceph monitor map (`monmap`) before proceeding, even when using the `--force` flag.
```bash
sudo microceph.ceph mon remove
diff --git a/doc/how-to/member_shutdown.md b/doc/how-to/member_shutdown.md
index da6d427d6..ab0de64aa 100644
--- a/doc/how-to/member_shutdown.md
+++ b/doc/how-to/member_shutdown.md
@@ -12,12 +12,16 @@ This guide provides instructions to safely shut down a MicroCloud cluster member
(howto-member-shutdown-instances)=
## Stop or live-migrate all instances on the cluster member
-To shut down a machine that is a MicroCloud cluster member, first ensure that it is not hosting any running LXD instances.
+To shut down a machine that is a MicroCloud cluster member, first ensure that it is not hosting any running LXD instances. Check to make sure that no project has any running instances on the target cluster member:
-You can stop all instances on a cluster member using the command:
+```bash
+lxc ls --all-projects
+```
+
+Explicitly shutting down LXD will shut down all instances running on that cluster member:
```bash
-lxc stop --all
+sudo snap stop lxd
```
Alternatively, for instances that can be {ref}`live-migrated `, you can migrate them to another cluster member without stopping them. See: {ref}`lxd:howto-instances-migrate` for more information.
diff --git a/doc/how-to/ovn_underlay.md b/doc/how-to/ovn_underlay.md
index f3d1fa0a5..5805b15b5 100644
--- a/doc/how-to/ovn_underlay.md
+++ b/doc/how-to/ovn_underlay.md
@@ -68,10 +68,10 @@ The following instructions build on our {ref}`multi-member tutorial
Sample output:
```{terminal}
-:input: snap list microcloud
:user: root
:host: instance
+snap list microcloud
Name Version Rev Tracking Publisher Notes
microcloud 2.1.0-3e8b183 1144 2/stable canonical✓ in-cohort,held
@@ -67,6 +67,7 @@ For more information about managing snap services, visit {ref}`snap:how-to-guide
## Related topics
How-to guides:
+
- {ref}`howto-update-upgrade`
- {ref}`howto-install`
diff --git a/doc/how-to/support.md b/doc/how-to/support.md
index e9423e2a5..d9c2d2ffd 100644
--- a/doc/how-to/support.md
+++ b/doc/how-to/support.md
@@ -9,7 +9,7 @@ You can seek support from the LXD developers as well as the wider community thro
### Forum
-Ask questions or engage in discussions in our [Discourse forum](https://discourse.ubuntu.com/c/lxd/microcloud/145).
+Ask questions or engage in discussions in our [Discourse forum](https://discourse.ubuntu.com/c/project/lxd/microcloud/145).
### Documentation
@@ -27,5 +27,5 @@ You can find additional resources on the [MicroCloud website](https://canonical.
LTS releases of MicroCloud receive standard support for five years, which means they receive continuous updates. Commercial support for MicroCloud is provided as part of [Ubuntu Pro](https://ubuntu.com/pro) (both Infra-only and full Ubuntu Pro). See the [full service description](https://ubuntu.com/legal/ubuntu-pro-description) for details.
-Managed solutions and firefighting support are also available for MicroCloud deployments. Visit [Managed services](https://ubuntu.com/managed) for details.
+Managed solutions and firefighting support are also available for MicroCloud deployments. Visit [Managed services](https://ubuntu.com/managed-infrastructure) for details.
diff --git a/doc/how-to/update_upgrade.md b/doc/how-to/update_upgrade.md
index 2138865b5..d3d7616a6 100644
--- a/doc/how-to/update_upgrade.md
+++ b/doc/how-to/update_upgrade.md
@@ -68,9 +68,9 @@ sudo snap refresh > --cohort="+"
After you set this flag, `snap list ` shows `in-cohort` in the `Notes` column. Example:
```{terminal}
-:input: snap list lxd
:user: root
:host: instance
+snap list lxd
Name Version Rev Tracking Publisher Notes
lxd 5.21.3-c5ae129 33110 5.21/stable canonical✓ in-cohort
diff --git a/doc/index.md b/doc/index.md
index 82190df4a..49df0c7bc 100644
--- a/doc/index.md
+++ b/doc/index.md
@@ -2,8 +2,7 @@
myst:
html_meta:
description: MicroCloud is a lightweight, open source cloud platform built on LXD, MicroCeph, and MicroOVN, ideal for private cloud, edge computing, and test labs.
-discourse: lxc:[Introducing MicroCloud](15871)
-relatedlinks: "[Install MicroCloud on Linux | Snap Store](https://snapcraft.io/microcloud)"
+relatedlinks: "[MicroCloud: your open source cloud platform](https://canonical.com/microcloud)"
---
(home)=
@@ -51,6 +50,17 @@ Also, while each component's documentation includes instructions for removing cl
---
+## How this documentation is organized
+
+This documentation uses the [Diátaxis documentation structure](https://diataxis.fr/).
+
+- The {ref}`tutorials` introduce you to MicroCloud concepts and usage.
+- The {ref}`howto` provide detailed setup and usage instructions, including how to access the UI and manage cluster members.
+- The {ref}`reference` guides provide technical details, release notes, and common CLI commands.
+- The {ref}`explanation` section includes topic overviews and detailed explanations of key concepts, such as local versus distributed storage.
+
+---
+
## Project and community
MicroCloud is a member of the [Canonical](https://canonical.com) family. It’s an open source project that warmly welcomes community contributions, suggestions, fixes, and constructive feedback.
@@ -58,7 +68,7 @@ MicroCloud is a member of the [Canonical](https://canonical.com) family. It’s
### Get involved
- {ref}`Support `
-- [Discussion forum](https://discourse.ubuntu.com/c/lxd/microcloud/145)
+- [Discussion forum](https://discourse.ubuntu.com/c/project/lxd/microcloud/145)
- {ref}`Contribute `
### Releases
@@ -73,15 +83,12 @@ MicroCloud is a member of the [Canonical](https://canonical.com) family. It’s
Thinking about using MicroCloud for your next project? [Get in touch](https://canonical.com/microcloud/contact-us)!
-
-
-
```{toctree}
:hidden:
:maxdepth: 2
self
-Tutorials
+/tutorial/index
/how-to/index
/reference/index
/explanation/index
diff --git a/doc/redirects.py b/doc/redirects.py
deleted file mode 100644
index dbd0f8254..000000000
--- a/doc/redirects.py
+++ /dev/null
@@ -1,9 +0,0 @@
-redirects = {
- 'tutorial/get_started': '../',
- 'explanation/initialisation': '../initialization',
- 'how-to/initialise': '../initialize',
- 'how-to/remove_machine': '../member_remove',
- 'how-to/add_machine': '../member_add',
- 'how-to/shutdown_machine': '../member_shutdown',
- 'how-to/commands': '../../reference/commands',
-}
diff --git a/doc/redirects.txt b/doc/redirects.txt
new file mode 100644
index 000000000..a1d1263de
--- /dev/null
+++ b/doc/redirects.txt
@@ -0,0 +1,15 @@
+# Client-side page redirects. Each mapping takes the format:
+#
+# "" ""
+#
+# Paths must be represented as source files relative to the root of the docs directory.
+# The old path must be a file that doesn't exist in the source. The current path must be
+# a file that does exist in the source.
+
+"tutorial/get_started" "tutorial/"
+"explanation/initialisation" "explanation/initialization"
+"how-to/initialise" "how-to/initialize"
+"how-to/remove_machine" "how-to/member_remove"
+"how-to/add_machine" "how-to/member_add"
+"how-to/shutdown_machine" "how-to/member_shutdown"
+"how-to/commands" "reference/commands"
\ No newline at end of file
diff --git a/doc/reference/releases-snaps.md b/doc/reference/releases-snaps.md
index 7816f925f..72406b500 100644
--- a/doc/reference/releases-snaps.md
+++ b/doc/reference/releases-snaps.md
@@ -24,7 +24,7 @@ Refer to {ref}`howto-update-upgrade` and {ref}`howto-snap` for additional detail
(ref-releases-microcloud)=
## MicroCloud releases
-The MicroCloud team maintains both Long Term Support (LTS) and feature releases in parallel. Release notes are published on [Discourse](https://discourse.ubuntu.com/c/lxd/microcloud/145/).
+The MicroCloud team maintains both Long Term Support (LTS) and feature releases in parallel. Release notes are published on [Discourse](https://discourse.ubuntu.com/c/project/lxd/microcloud/145).
(ref-releases-microcloud-lts)=
### LTS releases
diff --git a/doc/requirements.txt b/doc/requirements.txt
new file mode 100644
index 000000000..8f524d588
--- /dev/null
+++ b/doc/requirements.txt
@@ -0,0 +1,36 @@
+# Canonical theme (still needed for Furo theme and custom templates)
+canonical-sphinx~=0.6
+
+# Extensions previously auto-loaded by canonical-sphinx
+myst-parser~=4.0 # v5.0.0 causes version conflicts
+sphinx-autobuild==2025.8.25
+sphinx-design==0.6.1
+sphinx-notfound-page~=1.1
+sphinx-tabs~=3.5
+sphinxcontrib-jquery~=4.1
+sphinxext-opengraph~=0.13
+sphinx-rerediraffe>=0.0.3, <1.0.0
+
+# Extra extensions, previously bundled as canonical-sphinx-extensions
+sphinx-config-options~=0.1
+sphinx-filtered-toctree~=0.1
+sphinx-related-links~=0.1
+sphinx-roles~=0.1
+sphinx-terminal~=1.0
+sphinx-youtube-links~=0.1
+
+# Other dependencies
+packaging~=26.1
+sphinxcontrib-svg2pdfconverter[CairoSVG]~=2.1
+sphinx-last-updated-by-git~=0.3
+sphinx-sitemap~=2.9
+
+# Vale dependencies
+vale~=3.13
+
+# MicroCloud custom dependencies
+gitpython==3.1.50
+linkify-it-py==2.0.3
+pyyaml==6.0.3
+sphinx-copybutton==0.5.2
+watchfiles==1.1.1
diff --git a/doc/substitutions.yaml b/doc/reuse/substitutions.yaml
similarity index 100%
rename from doc/substitutions.yaml
rename to doc/reuse/substitutions.yaml
diff --git a/doc/tutorial/multi-member.md b/doc/tutorial/multi-member.md
index 01f13657b..04500e1c7 100644
--- a/doc/tutorial/multi-member.md
+++ b/doc/tutorial/multi-member.md
@@ -23,9 +23,9 @@ MicroCloud requires LXD version 5.21:
1. Run {command}`snap version` to find out if snap is installed on your system:
```{terminal}
- :input: snap version
:user: ubuntu
:host: lxd-host
+ snap version
snap 2.59.4
snapd 2.59.4
@@ -137,9 +137,9 @@ Complete the following steps to create the required disks in a LXD storage pool:
1. Check that the disks have been created correctly:
```{terminal}
- :input: lxc storage volume list disks
:user: ubuntu
:host: lxd-host
+ lxc storage volume list disks
+--------+---------+-------------+--------------+---------+
| TYPE | NAME | DESCRIPTION | CONTENT-TYPE | USED BY |
@@ -348,10 +348,10 @@ See the full process here for the initiating side:
(initialization-process)=
```{terminal}
-:input: microcloud init
:user: root
:host: micro1
:scroll:
+microcloud init
Do you want to set up more than one cluster member? (yes/no) [default=yes]: yes
Select an address for MicroCloud's internal traffic:
@@ -498,10 +498,10 @@ MicroCloud is ready
See the full process here for one of the joining sides (`micro2`):
```{terminal}
-:input: microcloud join
:user: root
:host: micro2
:scroll:
+microcloud join
Select an address for MicroCloud's internal traffic:
Space to select; enter to confirm; type to filter results.
@@ -542,10 +542,10 @@ We continue using `micro1`, but you will see the same results on the others.
1. Inspect the cluster setup:
```{terminal}
- :input: lxc cluster list
:user: root
:host: micro1
:scroll:
+ lxc cluster list
+--------+--------------------------+------------------+--------------+----------------+-------------+--------+-------------------+
| NAME | URL | ROLES | ARCHITECTURE | FAILURE DOMAIN | DESCRIPTION | STATE | MESSAGE |
@@ -559,7 +559,14 @@ We continue using `micro1`, but you will see the same results on the others.
+--------+--------------------------+------------------+--------------+----------------+-------------+--------+-------------------+
| micro4 | https://10.1.123.40:8443 | database-standby | x86_64 | default | | ONLINE | Fully operational |
+--------+--------------------------+------------------+--------------+----------------+-------------+--------+-------------------+
- :input: microcloud cluster list
+ ```
+
+ ```{terminal}
+ :user: root
+ :host: micro1
+ :scroll:
+ microcloud cluster list
+
+--------+------------------+----------+------------------------------------------------------------------+--------+
| NAME | ADDRESS | ROLE | FINGERPRINT | STATUS |
+--------+------------------+----------+------------------------------------------------------------------+--------+
@@ -571,7 +578,14 @@ We continue using `micro1`, but you will see the same results on the others.
+--------+------------------+----------+------------------------------------------------------------------+--------+
| micro4 | 10.1.123.40:9443 | stand-by | 649ec21815135104f1faa5fca099daddf995f554119c6e34706a2b31681ad1d7 | ONLINE |
+--------+------------------+----------+------------------------------------------------------------------+--------+
- :input: microceph cluster list
+ ```
+
+ ```{terminal}
+ :user: root
+ :host: micro1
+ :scroll:
+ microceph cluster list
+
+--------+------------------+----------+------------------------------------------------------------------+--------+
| NAME | ADDRESS | ROLE | FINGERPRINT | STATUS |
+--------+------------------+----------+------------------------------------------------------------------+--------+
@@ -583,7 +597,14 @@ We continue using `micro1`, but you will see the same results on the others.
+--------+------------------+----------+------------------------------------------------------------------+--------+
| micro4 | 10.1.123.40:7443 | stand-by | 9b75b396f6d59481b8c14221942d775cff4d27c5621b0b541eb5ba3245618093 | ONLINE |
+--------+------------------+----------+------------------------------------------------------------------+--------+
- :input: microovn cluster list
+ ```
+
+ ```{terminal}
+ :user: root
+ :host: micro1
+ :scroll:
+ microovn cluster list
+
+--------+------------------+----------+------------------------------------------------------------------+--------+
| NAME | ADDRESS | ROLE | FINGERPRINT | STATUS |
+--------+------------------+----------+------------------------------------------------------------------+--------+
@@ -600,10 +621,10 @@ We continue using `micro1`, but you will see the same results on the others.
1. Inspect the storage setup:
```{terminal}
- :input: lxc storage list
:user: root
:host: micro1
:scroll:
+ lxc storage list
+-----------+--------+--------------------------------------------+---------+---------+
| NAME | DRIVER | DESCRIPTION | USED BY | STATE |
@@ -614,7 +635,14 @@ We continue using `micro1`, but you will see the same results on the others.
+-----------+--------+--------------------------------------------+---------+---------+
| remote-fs | cephfs | Distributed file-system storage using Ceph | 1 | CREATED |
+-----------+--------+--------------------------------------------+---------+---------+
- :input: lxc storage info local
+ ```
+
+ ```{terminal}
+ :user: root
+ :host: micro1
+ :scroll:
+ lxc storage info local
+
info:
description: Local storage on ZFS
driver: zfs
@@ -631,7 +659,14 @@ We continue using `micro1`, but you will see the same results on the others.
- images (location "micro2")
- images (location "micro3")
- images (location "micro4")
- :input: lxc storage info remote
+ ```
+
+ ```{terminal}
+ :user: root
+ :host: micro1
+ :scroll:
+ lxc storage info remote
+
info:
description: Distributed storage on Ceph
driver: ceph
@@ -641,7 +676,14 @@ We continue using `micro1`, but you will see the same results on the others.
used by:
profiles:
- default
- :input: lxc storage info remote-fs
+ ```
+
+ ```{terminal}
+ :user: root
+ :host: micro1
+ :scroll:
+ lxc storage info remote-fs
+
info:
description: Distributed file-system storage using CephFS
driver: cephfs
@@ -654,10 +696,10 @@ We continue using `micro1`, but you will see the same results on the others.
1. Inspect the OVN network setup:
```{terminal}
- :input: lxc network list
:user: root
:host: micro1
:scroll:
+ lxc network list
+---------+----------+---------+-----------------+--------------------------+-------------+---------+---------+
| NAME | TYPE | MANAGED | IPV4 | IPV6 | DESCRIPTION | USED BY | STATE |
@@ -674,7 +716,14 @@ We continue using `micro1`, but you will see the same results on the others.
+---------+----------+---------+-----------------+--------------------------+-------------+---------+---------+
| lxdovn1 | bridge | NO | | | | 0 | |
+---------+----------+---------+-----------------+--------------------------+-------------+---------+---------+
- :input: lxc network show default
+ ```
+
+ ```{terminal}
+ :user: root
+ :host: micro1
+ :scroll:
+ lxc network show default
+
config:
bridge.mtu: "1442"
ipv4.address: 198.51.100.1/24
@@ -703,11 +752,12 @@ We continue using `micro1`, but you will see the same results on the others.
1. Within the output of the previous command (`lxc network show default`), find the value for `volatile.network.ipv4.address`. This is the virtual router's IPv4 address.
1. Ping that IPv4 address.
+
```{terminal}
- :input: ping 192.0.2.100
:user: root
:host: micro1
:scroll:
+ ping 192.0.2.100
PING 192.0.2.100 (192.0.2.100) 56(84) bytes of data.
64 bytes from 192.0.2.100: icmp_seq=1 ttl=253 time=2.05 ms
@@ -717,24 +767,15 @@ We continue using `micro1`, but you will see the same results on the others.
--- 192.0.2.100 ping statistics ---
4 packets transmitted, 3 received, 25% packet loss, time 3005ms
rtt min/avg/max/mdev = 1.777/1.945/2.052/0.120 ms
- :input: ping6 -n 2001:db8:e647:610d:216:3eff:fe96:ed5c
- PING 2001:db8:e647:610d:216:3eff:fe96:ed5c(2001:db8:e647:610d:216:3eff:fe96:ed5c) 56 data bytes
- 64 bytes from 2001:db8:e647:610d:216:3eff:fe96:ed5c: icmp_seq=1 ttl=253 time=1.61 ms
- 64 bytes from 2001:db8:e647:610d:216:3eff:fe96:ed5c: icmp_seq=2 ttl=253 time=1.99 ms
- 64 bytes from 2001:db8:e647:610d:216:3eff:fe96:ed5c: icmp_seq=3 ttl=253 time=15.7 ms
- ^C
- --- 2001:db8:e647:610d:216:3eff:fe96:ed5c ping statistics ---
- 3 packets transmitted, 3 received, 0% packet loss, time 2004ms
- rtt min/avg/max/mdev = 1.606/6.432/15.704/6.558 ms
```
1. Inspect the default profile:
```{terminal}
- :input: lxc profile show default
:user: root
:host: micro1
:scroll:
+ lxc profile show default
config: {}
description: ""
@@ -771,10 +812,10 @@ Now that your MicroCloud cluster is ready to use, let's launch a few instances:
Note that the instances are running on different cluster members.
```{terminal}
- :input: lxc list
:user: root
:host: micro1
:scroll:
+ lxc list
+------+---------+---------------------+----------------------------------------------+-----------------+-----------+----------+
| NAME | STATE | IPV4 | IPV6 | TYPE | SNAPSHOTS | LOCATION |
@@ -791,10 +832,10 @@ Now that your MicroCloud cluster is ready to use, let's launch a few instances:
Note that the instance volumes are located on the specified storage pools.
```{terminal}
- :input: lxc storage volume list remote
:user: root
:host: micro1
:scroll:
+ lxc storage volume list remote
+-----------------+------------------------------------------------------------------+-------------+--------------+---------+----------+
| TYPE | NAME | DESCRIPTION | CONTENT-TYPE | USED BY | LOCATION |
@@ -807,7 +848,14 @@ Now that your MicroCloud cluster is ready to use, let's launch a few instances:
+-----------------+------------------------------------------------------------------+-------------+--------------+---------+----------+
| virtual-machine | u3 | | block | 1 | |
+-----------------+------------------------------------------------------------------+-------------+--------------+---------+----------+
- :input: lxc storage volume list local
+ ```
+
+ ```{terminal}
+ :user: root
+ :host: micro1
+ :scroll:
+ lxc storage volume list local
+
+-----------+------------------------------------------------------------------+-------------+--------------+---------+----------+
| TYPE | NAME | DESCRIPTION | CONTENT-TYPE | USED BY | LOCATION |
+-----------+------------------------------------------------------------------+-------------+--------------+---------+----------+
@@ -841,10 +889,10 @@ You can, however, create a different network to isolate some instances from othe
1. Check the list of running instances:
```{terminal}
- :input: lxc list
:user: root
:host: micro1
:scroll:
+ lxc list
+------+---------+---------------------+----------------------------------------------+-----------------+-----------+----------+
| NAME | STATE | IPV4 | IPV6 | TYPE | SNAPSHOTS | LOCATION |
@@ -864,10 +912,10 @@ You can, however, create a different network to isolate some instances from othe
1. Ping the IPv4 address of `u2`:
```{terminal}
- :input: ping 198.51.100.3
:user: root
:host: u1
:scroll:
+ ping 198.51.100.3
PING 198.51.100.3 (198.51.100.3) 56(84) bytes of data.
64 bytes from 198.51.100.3: icmp_seq=1 ttl=64 time=1.33 ms
@@ -882,10 +930,10 @@ You can, however, create a different network to isolate some instances from othe
1. Ping the IPv6 address of `u3`:
```{terminal}
- :input: ping6 -n 2001:db8:d960:91cf:216:3eff:fe66:f24b
:user: root
:host: u1
:scroll:
+ ping6 -n 2001:db8:d960:91cf:216:3eff:fe66:f24b
PING 2001:db8:d960:91cf:216:3eff:fe66:f24b(2001:db8:d960:91cf:216:3eff:fe66:f24b) 56 data bytes
64 bytes from 2001:db8:d960:91cf:216:3eff:fe66:f24b: icmp_seq=1 ttl=64 time=16.8 ms
@@ -900,10 +948,10 @@ You can, however, create a different network to isolate some instances from othe
1. Confirm that the instance has connectivity to the outside world:
```{terminal}
- :input: ping www.example.com
:user: root
:host: u1
:scroll:
+ ping www.example.com
PING www.example.com (93.184.216.34) 56(84) bytes of data.
64 bytes from 93.184.216.34 (93.184.216.34): icmp_seq=1 ttl=49 time=111 ms
@@ -928,10 +976,10 @@ You can, however, create a different network to isolate some instances from othe
1. Show information about the new network:
```{terminal}
- :input: lxc network show isolated
:user: root
:host: micro1
:scroll:
+ lxc network show isolated
config:
bridge.mtu: "1442"
@@ -958,10 +1006,10 @@ You can, however, create a different network to isolate some instances from othe
1. Check that you can ping the `volatile.network.ipv4.address`:
```{terminal}
- :input: ping 192.0.2.101
:user: root
:host: micro1
:scroll:
+ ping 192.0.2.101
PING 192.0.2.101 (192.0.2.101) 56(84) bytes of data.
64 bytes from 192.0.2.101: icmp_seq=1 ttl=253 time=1.25 ms
@@ -984,10 +1032,10 @@ You can, however, create a different network to isolate some instances from othe
1. Confirm that the instance has connectivity to the outside world:
```{terminal}
- :input: ping www.example.com
:user: root
:host: u4
:scroll:
+ ping www.example.com
PING www.example.com (93.184.216.34) 56(84) bytes of data.
64 bytes from 93.184.216.34 (93.184.216.34): icmp_seq=1 ttl=49 time=95.6 ms
@@ -1002,10 +1050,10 @@ You can, however, create a different network to isolate some instances from othe
1. Ping the IPv4 address of `u2`:
```{terminal}
- :input: ping 198.51.100.3
:user: root
:host: u4
:scroll:
+ ping 198.51.100.3
PING 198.51.100.3 (198.51.100.3) 56(84) bytes of data.
^C
@@ -1023,10 +1071,10 @@ See {ref}`lxd:access-ui` for more information.
1. Check the LXD cluster list to determine the IP addresses of the cluster members:
```{terminal}
- :input: lxc cluster list
:user: root
:host: micro1
:scroll:
+ lxc cluster list
+--------+--------------------------+------------------+--------------+----------------+-------------+--------+-------------------+
| NAME | URL | ROLES | ARCHITECTURE | FAILURE DOMAIN | DESCRIPTION | STATE | MESSAGE |
diff --git a/doc/tutorial/single-member.md b/doc/tutorial/single-member.md
index 46eb3c27f..d71f171e0 100644
--- a/doc/tutorial/single-member.md
+++ b/doc/tutorial/single-member.md
@@ -103,9 +103,10 @@ sudo microcloud init
MicroCloud will ask if you want to set up more than one cluster member. Enter `no`:
```{terminal}
-:input: sudo microcloud init
:user: ubuntu
:host: micro1
+sudo microcloud init
+
Waiting for services to start ...
Do you want to set up more than one cluster member? (yes/no) [default=yes]: no
```
@@ -116,6 +117,8 @@ Do you want to set up more than one cluster member? (yes/no) [default=yes]: no
Next, MicroCloud needs to configure the network interface to use for internal traffic. If there is only one interface suitable for internal traffic, MicroCloud detects its address automatically and shows output similar to the following:
```{terminal}
+:output-only:
+
Using address 192.0.2.10 for MicroCloud
```
@@ -127,6 +130,8 @@ If there are multiple suitable interfaces, MicroCloud instead shows a list of op
Next, MicroCloud will ask about local storage:
```{terminal}
+:output-only:
+
Would you like to set up local storage? (yes/no) [default=yes]:
```
@@ -139,6 +144,8 @@ Next, MicroCloud will ask you to select which disks to wipe. If the disk you cho
Next, MicroCloud will ask about distributed storage:
```{terminal}
+:output-only:
+
Would you like to set up distributed storage? (yes/no) [default=yes]:
```
@@ -149,6 +156,8 @@ MicroCloud will again ask you to select which disks to wipe. If the disk you cho
You'll see the following error message, and you'll be asked if you want to change the disk selection. Do not accept the default this time. Enter `no`:
```{terminal}
+:output-only:
+
! Warning: Disk configuration does not meet recommendations for fault tolerance. At least 3 systems must supply disks (1 currently supplying). Continuing with this configuration will inhibit MicroCloud's ability to retain data on system failure
Change disk selection? (yes/no) [default=yes]: no
```
@@ -158,6 +167,8 @@ A working distributed storage setup requires a multi-member cluster with at leas
Next, MicroCloud will ask about disk encryption:
```{terminal}
+:output-only:
+
Do you want to encrypt the selected disks? (yes/no) [default=no]:
```
@@ -171,6 +182,8 @@ The next set of questions configures {ref}`CephFS remote storage
:user: ubuntu
:host: micro1
+lxc storage info
```
Example:
@@ -396,10 +444,10 @@ lxc network list
You'll see output similar to this, along with any additional network interfaces on your machine:
```{terminal}
-:input: lxc network list
:user: ubuntu
:host: micro1
:scroll:
+lxc network list
+---------+----------+---------+----------------+---------------------------+---------------------+---------+---------+
| NAME | TYPE | MANAGED | IPV4 | IPV6 | DESCRIPTION | USED BY | STATE |
@@ -421,9 +469,9 @@ lxc network show default
You should see output similar to this:
```{terminal}
-:input: lxc network show default
:user: ubuntu
:host: micro1
+lxc network show default
name: default
description: Default OVN network
@@ -454,7 +502,7 @@ Confirm that you can ping the virtual router:
```{terminal}
:user: ubuntu
:host: micro1
-:input: ping -c 4
+ping -c 4
```
(tutorial-single-launch-instances)=
@@ -497,8 +545,8 @@ You should see output similar to this:
```{terminal}
:user: ubuntu
:host: micro1
-:input: lxc list
:scroll:
+lxc list
+------+---------+---------------------+-------------------------------------------------+-----------------+-----------+----------+
| NAME | STATE | IPV4 | IPV6 | TYPE | SNAPSHOTS | LOCATION |
@@ -523,8 +571,9 @@ Expect output similar to this:
```{terminal}
:user: ubuntu
:host: micro1
-:input: lxc storage volume list remote
:scroll:
+lxc storage volume list remote
+
+-----------------+------------------------------------------------------------------+-------------+--------------+---------+----------+
| TYPE | NAME | DESCRIPTION | CONTENT-TYPE | USED BY | LOCATION |
+-----------------+------------------------------------------------------------------+-------------+--------------+---------+----------+
@@ -536,7 +585,14 @@ Expect output similar to this:
+-----------------+------------------------------------------------------------------+-------------+--------------+---------+----------+
| virtual-machine | u3 | | block | 1 | |
+-----------------+------------------------------------------------------------------+-------------+--------------+---------+----------+
-:input: lxc storage volume list local
+```
+
+```{terminal}
+:user: ubuntu
+:host: micro1
+:scroll:
+lxc storage volume list local
+
+-----------+------------------------------------------------------------------+-------------+--------------+---------+----------+
| TYPE | NAME | DESCRIPTION | CONTENT-TYPE | USED BY | LOCATION |
+-----------+------------------------------------------------------------------+-------------+--------------+---------+----------+
@@ -579,7 +635,7 @@ From within that shell, ping the IPv4 address of your `u2` instance. If you did
```{terminal}
:user: root
:host: u1
-:input: ping -c 4
+ping -c 4
```
Next, ping the IPv6 address of your `u3` instance:
@@ -587,7 +643,7 @@ Next, ping the IPv6 address of your `u3` instance:
```{terminal}
:user: root
:host: u1
-:input: ping -c 4
+ping -c 4
```
Check if the `u1` instance also has connectivity to the outside world by pinging an external IP. The example below pings the public Google DNS server IP address:
@@ -632,7 +688,7 @@ Check that you can ping the `volatile.network.ipv4.address` for the new `isolate
```{terminal}
:user: ubuntu
:host: micro1
-:input: ping -c 4
+ping -c 4
```
Launch a new Ubuntu container that uses the new network:
@@ -659,7 +715,7 @@ Next, try to ping the IPv4 address of one of the other instances, such as `u1`:
```{terminal}
:user: ubuntu
:host: micro1
-:input: ping -c 4
+ping -c 4
```
This ping should fail. Other instances should not be reachable because they are on a different OVN subnet.
@@ -691,8 +747,8 @@ Example:
```{terminal}
:user: ubuntu
:host: micro1
-:input: lxc cluster list
:scroll:
+lxc cluster list
+--------+--------------------------+-----------------+--------------+----------------+-------------+--------+-------------------+
| NAME | URL | ROLES | ARCHITECTURE | FAILURE DOMAIN | DESCRIPTION | STATE | MESSAGE |
 }})
-