- {# ru-fu: replaced RTD icons with our links #}
+ {# mod: replaced RTD icons with our links #}
{% if discourse %}
@@ -71,6 +80,18 @@
{% endif %}
+ {% if mattermost %}
+
+ {% endif %}
+
+ {% if matrix %}
+
+ {% endif %}
+
{% if github_url and github_version and github_folder %}
{% if github_issues %}
diff --git a/docs/.sphinx/_templates/header.html b/docs/.sphinx/_templates/header.html
new file mode 100644
index 000000000..1a128b6f8
--- /dev/null
+++ b/docs/.sphinx/_templates/header.html
@@ -0,0 +1,36 @@
+
diff --git a/docs/_templates/page.html b/docs/.sphinx/_templates/page.html
similarity index 93%
rename from docs/_templates/page.html
rename to docs/.sphinx/_templates/page.html
index ede3495c8..bda306109 100644
--- a/docs/_templates/page.html
+++ b/docs/.sphinx/_templates/page.html
@@ -4,6 +4,11 @@
{% include "footer.html" %}
{% endblock footer %}
+{% block body -%}
+ {% include "header.html" %}
+ {{ super() }}
+{%- endblock body %}
+
{% if meta and ((meta.discourse and discourse_prefix) or meta.relatedlinks) %}
{% set furo_hide_toc_orig = furo_hide_toc %}
{% set furo_hide_toc=false %}
diff --git a/docs/.sphinx/_templates/sidebar/search.html b/docs/.sphinx/_templates/sidebar/search.html
new file mode 100644
index 000000000..644a5ef6a
--- /dev/null
+++ b/docs/.sphinx/_templates/sidebar/search.html
@@ -0,0 +1,7 @@
+
+
diff --git a/docs/.sphinx/build_requirements.py b/docs/.sphinx/build_requirements.py
new file mode 100644
index 000000000..d7fdf238d
--- /dev/null
+++ b/docs/.sphinx/build_requirements.py
@@ -0,0 +1,125 @@
+# ruff: noqa
+import sys
+
+sys.path.append('./')
+from custom_conf import *
+
+# The file contains helper functions and the mechanism to build the
+# .sphinx/requirements.txt file that is needed to set up the virtual
+# environment.
+
+# You should not do any modifications to this file. Put your custom
+# requirements into the custom_required_modules array in the custom_conf.py
+# file. If you need to change this file, contribute the changes upstream.
+
+legacyCanonicalSphinxExtensionNames = [
+ "youtube-links",
+ "related-links",
+ "custom-rst-roles",
+ "terminal-output"
+ ]
+
+def IsAnyCanonicalSphinxExtensionUsed():
+ for extension in custom_extensions:
+ if (extension.startswith("canonical.") or
+ extension in legacyCanonicalSphinxExtensionNames):
+ return True
+
+ return False
+
+def IsNotFoundExtensionUsed():
+ return "notfound.extension" in custom_extensions
+
+def IsSphinxTabsUsed():
+ for extension in custom_extensions:
+ if extension.startswith("sphinx_tabs."):
+ return True
+
+ return False
+
+def AreRedirectsDefined():
+ return ("sphinx_reredirects" in custom_extensions) or (
+ ("redirects" in globals()) and \
+ (redirects is not None) and \
+ (len(redirects) > 0))
+
+def IsOpenGraphConfigured():
+ if "sphinxext.opengraph" in custom_extensions:
+ return True
+
+ for global_variable_name in list(globals()):
+ if global_variable_name.startswith("ogp_"):
+ return True
+
+ return False
+
+def IsMyStParserUsed():
+ return ("myst_parser" in custom_extensions) or \
+ ("custom_myst_extensions" in globals())
+
+def DeduplicateExtensions(extensionNames: [str]):
+ extensionNames = dict.fromkeys(extensionNames)
+ resultList = []
+ encounteredCanonicalExtensions = []
+
+ for extensionName in extensionNames:
+ if extensionName in legacyCanonicalSphinxExtensionNames:
+ extensionName = "canonical." + extensionName
+
+ if extensionName.startswith("canonical."):
+ if extensionName not in encounteredCanonicalExtensions:
+ encounteredCanonicalExtensions.append(extensionName)
+ resultList.append(extensionName)
+ else:
+ resultList.append(extensionName)
+
+ return resultList
+
+if __name__ == "__main__":
+ requirements = [
+ "furo",
+ "pyspelling",
+ "sphinx==6.2.1",
+ "sphinx-autobuild",
+ "sphinx-copybutton",
+ "sphinx-design",
+ "sphinxcontrib-jquery"
+ ]
+
+ requirements.extend(custom_required_modules)
+
+ if IsAnyCanonicalSphinxExtensionUsed():
+ requirements.append("canonical-sphinx-extensions")
+
+ if IsNotFoundExtensionUsed():
+ requirements.append("sphinx-notfound-page")
+
+ if IsSphinxTabsUsed():
+ requirements.append("sphinx-tabs")
+
+ if AreRedirectsDefined():
+ requirements.append("sphinx-reredirects")
+
+ if IsOpenGraphConfigured():
+ requirements.append("sphinxext-opengraph")
+
+ if IsMyStParserUsed():
+ requirements.append("myst-parser")
+ requirements.append("linkify-it-py")
+
+ # removes duplicate entries
+ requirements = list(dict.fromkeys(requirements))
+ requirements.sort()
+
+ with open(".sphinx/requirements.txt", 'w') as requirements_file:
+ requirements_file.write(
+ "# DO NOT MODIFY THIS FILE DIRECTLY!\n"
+ "#\n"
+ "# This file is generated automatically.\n"
+ "# Add custom requirements to the custom_required_modules\n"
+ "# array in the custom_conf.py file and run:\n"
+ "# make clean && make install\n")
+
+ for requirement in requirements:
+ requirements_file.write(requirement)
+ requirements_file.write('\n')
diff --git a/docs/.sphinx/pa11y.json b/docs/.sphinx/pa11y.json
new file mode 100644
index 000000000..8df0cb9cb
--- /dev/null
+++ b/docs/.sphinx/pa11y.json
@@ -0,0 +1,9 @@
+{
+ "chromeLaunchConfig": {
+ "args": [
+ "--no-sandbox"
+ ]
+ },
+ "reporter": "cli",
+ "standard": "WCAG2AA"
+}
\ No newline at end of file
diff --git a/docs/.sphinx/spellingcheck.yaml b/docs/.sphinx/spellingcheck.yaml
new file mode 100644
index 000000000..fc9d3c503
--- /dev/null
+++ b/docs/.sphinx/spellingcheck.yaml
@@ -0,0 +1,29 @@
+matrix:
+- name: rST files
+ aspell:
+ lang: en
+ d: en_GB
+ dictionary:
+ wordlists:
+ - .wordlist.txt
+ - .custom_wordlist.txt
+ output: .sphinx/.wordlist.dic
+ sources:
+ - _build/**/*.html
+ pipeline:
+ - pyspelling.filters.html:
+ comments: false
+ attributes:
+ - title
+ - alt
+ ignores:
+ - code
+ - pre
+ - spellexception
+ - link
+ - title
+ - div.relatedlinks
+ - strong.command
+ - div.visually-hidden
+ - img
+ - a.p-navigation__link
diff --git a/docs/.wokeignore b/docs/.wokeignore
new file mode 100644
index 000000000..ae0b80f57
--- /dev/null
+++ b/docs/.wokeignore
@@ -0,0 +1,3 @@
+# the cheat sheets contain a link to a repository with a block word which we
+# cannot avoid for now, ie
+# https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
diff --git a/docs/.wordlist.txt b/docs/.wordlist.txt
new file mode 100644
index 000000000..1d1858108
--- /dev/null
+++ b/docs/.wordlist.txt
@@ -0,0 +1,48 @@
+addons
+API
+APIs
+balancer
+Charmhub
+CLI
+Diátaxis
+dropdown
+EBS
+EKS
+enablement
+favicon
+Furo
+Git
+GitHub
+Grafana
+IAM
+installable
+JSON
+Juju
+Kubeflow
+Kubernetes
+Launchpad
+LTS
+Makefile
+Mattermost
+MyST
+namespace
+namespaces
+NodePort
+observability
+OEM
+OLM
+Permalink
+pre
+Quickstart
+ReadMe
+reST
+reStructuredText
+RTD
+subdirectories
+subfolders
+subtree
+Ubuntu
+UI
+UUID
+VM
+YAML
diff --git a/docs/_static/custom.css b/docs/_static/custom.css
deleted file mode 100644
index cad94b74c..000000000
--- a/docs/_static/custom.css
+++ /dev/null
@@ -1,189 +0,0 @@
-/** Fix the font weight (300 for normal, 400 for slightly bold) **/
-
-div.page, h1, h2, h3, h4, h5, h6, .sidebar-tree .current-page>.reference, button, input, optgroup, select, textarea, th.head {
- font-weight: 300
-}
-
-.toc-tree li.scroll-current>.reference, dl.glossary dt, dl.simple dt, dl:not([class]) dt {
- font-weight: 400;
-}
-
-/** Table styling **/
-
-th.head {
- text-transform: uppercase;
- font-size: var(--font-size--small);
-}
-
-table.docutils {
- border: 0;
- box-shadow: none;
- width:100%;
-}
-
-table.docutils td, table.docutils th, table.docutils td:last-child, table.docutils th:last-child, table.docutils td:first-child, table.docutils th:first-child {
- border-right: none;
- border-left: none;
-}
-
-/* Allow to centre text horizontally in table data cells */
-table.align-center {
- text-align: center !important;
-}
-
-/** No rounded corners **/
-
-.admonition, code.literal, .sphinx-tabs-tab, .sphinx-tabs-panel, .highlight {
- border-radius: 0;
-}
-
-/** Admonition styling **/
-
-.admonition {
- border-top: 1px solid #d9d9d9;
- border-right: 1px solid #d9d9d9;
- border-bottom: 1px solid #d9d9d9;
-}
-
-/** Color for the "copy link" symbol next to headings **/
-
-a.headerlink {
- color: var(--color-brand-primary);
-}
-
-/** Line to the left of the current navigation entry **/
-
-.sidebar-tree li.current-page {
- border-left: 2px solid var(--color-brand-primary);
-}
-
-/** Some tweaks for issue #16 **/
-
-[role="tablist"] {
- border-bottom: 1px solid var(--color-sidebar-item-background--hover);
-}
-
-.sphinx-tabs-tab[aria-selected="true"] {
- border: 0;
- border-bottom: 2px solid var(--color-brand-primary);
- background-color: var(--color-sidebar-item-background--current);
- font-weight:300;
-}
-
-.sphinx-tabs-tab{
- color: var(--color-brand-primary);
- font-weight:300;
-}
-
-.sphinx-tabs-panel {
- border: 0;
- border-bottom: 1px solid var(--color-sidebar-item-background--hover);
- background: var(--color-background-primary);
-}
-
-button.sphinx-tabs-tab:hover {
- background-color: var(--color-sidebar-item-background--hover);
-}
-
-/** Custom classes to fix scrolling in tables by decreasing the
- font size or breaking certain columns.
- Specify the classes in the Markdown file with, for example:
- ```{rst-class} break-col-4 min-width-4-8
- ```
-**/
-
-table.dec-font-size {
- font-size: smaller;
-}
-table.break-col-1 td.text-left:first-child {
- word-break: break-word;
-}
-table.break-col-4 td.text-left:nth-child(4) {
- word-break: break-word;
-}
-table.min-width-1-15 td.text-left:first-child {
- min-width: 15em;
-}
-table.min-width-4-8 td.text-left:nth-child(4) {
- min-width: 8em;
-}
-
-/** Underline for abbreviations **/
-
-abbr[title] {
- text-decoration: underline solid #cdcdcd;
-}
-
-/** Use the same style for right-details as for left-details **/
-.bottom-of-page .right-details {
- font-size: var(--font-size--small);
- display: block;
-}
-
-/** Version switcher */
-button.version_select {
- color: var(--color-foreground-primary);
- background-color: var(--color-toc-background);
- padding: 5px 10px;
- border: none;
-}
-
-.version_select:hover, .version_select:focus {
- background-color: var(--color-sidebar-item-background--hover);
-}
-
-.version_dropdown {
- position: relative;
- display: inline-block;
- text-align: right;
- font-size: var(--sidebar-item-font-size);
-}
-
-.available_versions {
- display: none;
- position: absolute;
- right: 0px;
- background-color: var(--color-toc-background);
- box-shadow: 0px 8px 16px 0px rgba(0,0,0,0.2);
- z-index: 11;
-}
-
-.available_versions a {
- color: var(--color-foreground-primary);
- padding: 12px 16px;
- text-decoration: none;
- display: block;
-}
-
-.available_versions a:hover {background-color: var(--color-sidebar-item-background--current)}
-
-.show {display:block;}
-
-/** Fix for nested numbered list - the nested list is lettered **/
-ol.arabic ol.arabic {
- list-style: lower-alpha;
-}
-
-/** Make expandable sections look like links **/
-details summary {
- color: var(--color-link);
-}
-
-/** Fix the styling of the version box for readthedocs **/
-
-#furo-readthedocs-versions .rst-versions, #furo-readthedocs-versions .rst-current-version, #furo-readthedocs-versions:focus-within .rst-current-version, #furo-readthedocs-versions:hover .rst-current-version {
- background: var(--color-sidebar-item-background--hover);
-}
-
-.rst-versions .rst-other-versions dd a {
- color: var(--color-link);
-}
-
-#furo-readthedocs-versions:focus-within .rst-current-version .fa-book, #furo-readthedocs-versions:hover .rst-current-version .fa-book, .rst-versions .rst-other-versions {
- color: var(--color-sidebar-link-text);
-}
-
-.rst-versions .rst-current-version {
- color: var(--color-version-popup);
- font-weight: bolder;
-}
diff --git a/docs/_static/favicon.png b/docs/_static/favicon.png
deleted file mode 100644
index c7109908f..000000000
Binary files a/docs/_static/favicon.png and /dev/null differ
diff --git a/docs/_templates/base.html b/docs/_templates/base.html
deleted file mode 100644
index 62ffe6b8c..000000000
--- a/docs/_templates/base.html
+++ /dev/null
@@ -1,7 +0,0 @@
-{% extends "furo/base.html" %}
-
-{% block theme_scripts %}
-
-{% endblock theme_scripts %}
diff --git a/docs/conf.py b/docs/conf.py
index 53011cbb9..fd4e82fe2 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,272 +1,166 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# For a full list of options see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
-
-# NOTE: a fair bit of this is copied from:
-# https://github.com/canonical/sphinx-docs-starter-pack/blob/main/conf.py
-
-
-# -- Path setup --------------------------------------------------------------
-
-import furo
-import furo.navigation
-import pathlib
import sys
+import os
-sys.path.insert(0, str(pathlib.Path(__file__).parent.parent))
-
-
-# Furo patch to get local TOC to show in sidebar (as sphinx-rtd-theme did)
-# See https://github.com/pradyunsg/furo/blob/490527b2aef00b1198770c3389a1979911ee1fcb/src/furo/__init__.py#L115-L128
-
-_old_compute_navigation_tree = furo._compute_navigation_tree
-
-
-def _compute_navigation_tree(context):
- tree_html = _old_compute_navigation_tree(context)
- if not tree_html and context.get("toc"):
- tree_html = furo.navigation.get_navigation_tree(context["toc"])
- return tree_html
-
+sys.path.append('./')
+from custom_conf import *
+sys.path.append('.sphinx/')
+from build_requirements import *
-furo._compute_navigation_tree = _compute_navigation_tree
-
-
-# Pull in fix from https://github.com/sphinx-doc/sphinx/pull/11222/files to fix
-# "invalid signature for autoattribute ('ops.pebble::ServiceDict.backoff-delay')"
-import re # noqa: E402
-import sphinx.ext.autodoc # noqa: E402
-sphinx.ext.autodoc.py_ext_sig_re = re.compile(
- r'''^ ([\w.]+::)? # explicit module name
- ([\w.]+\.)? # module and/or class name(s)
- ([^.()]+) \s* # thing name
- (?: \((.*)\) # optional: arguments
- (?:\s* -> \s* (.*))? # return annotation
- )? $ # and nothing more
- ''', re.VERBOSE)
-
-
-# -- Project information -----------------------------------------------------
+# Configuration file for the Sphinx documentation builder.
+# You should not do any modifications to this file. Put your custom
+# configuration into the custom_conf.py file.
+# If you need to change this file, contribute the changes upstream.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
-project = 'The ops library'
-copyright = '2019-2023, Canonical Ltd.'
-author = 'Canonical Ltd'
+############################################################
+### Extensions
+############################################################
-html_favicon = "_static/favicon.png"
+extensions = [
+ 'sphinx_design',
+ 'sphinx_copybutton',
+ 'sphinxcontrib.jquery',
+]
-html_context = {
- "discourse": "https://discourse.charmhub.io/",
- "discourse_prefix": "https://discourse.charmhub.io/t/",
- "github_url": "https://github.com/canonical/operator",
- "github_version": "main",
- "github_folder": "/docs/",
- "github_issues": "enabled",
+# Only add redirects extension if any redirects are specified.
+if AreRedirectsDefined():
+ extensions.append('sphinx_reredirects')
+
+# Only add myst extensions if any configuration is present.
+if IsMyStParserUsed():
+ extensions.append('myst_parser')
+
+ # Additional MyST syntax
+ myst_enable_extensions = [
+ 'substitution',
+ 'deflist',
+ 'linkify'
+ ]
+ myst_enable_extensions.extend(custom_myst_extensions)
+
+# Only add Open Graph extension if any configuration is present.
+if IsOpenGraphConfigured():
+ extensions.append('sphinxext.opengraph')
+
+extensions.extend(custom_extensions)
+extensions = DeduplicateExtensions(extensions)
+
+### Configuration for extensions
+
+# Used for related links
+if not 'discourse_prefix' in html_context and 'discourse' in html_context:
+ html_context['discourse_prefix'] = html_context['discourse'] + '/t/'
+
+# The URL prefix for the notfound extension depends on whether the documentation uses versions.
+# For documentation on documentation.ubuntu.com, we also must add the slug.
+url_version = ''
+url_lang = ''
+
+# Determine if the URL uses versions and language
+if 'READTHEDOCS_CANONICAL_URL' in os.environ and os.environ['READTHEDOCS_CANONICAL_URL']:
+ url_parts = os.environ['READTHEDOCS_CANONICAL_URL'].split('/')
+
+ if len(url_parts) >= 2 and 'READTHEDOCS_VERSION' in os.environ and os.environ['READTHEDOCS_VERSION'] == url_parts[-2]:
+ url_version = url_parts[-2] + '/'
+
+ if len(url_parts) >= 3 and 'READTHEDOCS_LANGUAGE' in os.environ and os.environ['READTHEDOCS_LANGUAGE'] == url_parts[-3]:
+ url_lang = url_parts[-3] + '/'
+
+# Set notfound_urls_prefix to the slug (if defined) and the version/language affix
+if slug:
+ notfound_urls_prefix = '/' + slug + '/' + url_lang + url_version
+elif len(url_lang + url_version) > 0:
+ notfound_urls_prefix = '/' + url_lang + url_version
+else:
+ notfound_urls_prefix = ''
+
+notfound_context = {
+ 'title': 'Page not found',
+ 'body': '
Sorry, but the documentation page that you are looking for was not found.
\n\n
Documentation 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).
\n
You can try to use the navigation to locate the content you\'re looking for, or search for a similar page.
\n',
}
-# -- General configuration ---------------------------------------------------
-
-# If true, Sphinx will warn about all references where the target
-# cannot be found.
-nitpicky = True
-
-# A list of (type, target) tuples (by default empty) that should be ignored when
-# generating warnings in “nitpicky mode”. Note that type should include the
-# domain name if present. Example entries would be ('py:func', 'int') or
-# ('envvar', 'LD_LIBRARY_PATH').
-nitpick_ignore = [
- # Please keep this list sorted alphabetically.
- ('py:class', '_ChangeDict'),
- ('py:class', '_CheckInfoDict'),
- ('py:class', '_FileInfoDict'),
- ('py:class', '_NoticeDict'),
- ('py:class', '_ProgressDict'),
- ('py:class', '_Readable'),
- ('py:class', '_RelationMetaDict'),
- ('py:class', '_ResourceMetaDict'),
- ('py:class', '_StorageMetaDict'),
- ('py:class', '_TaskDict'),
- ('py:class', '_TextOrBinaryIO'),
- ('py:class', '_WarningDict'),
- ('py:class', '_Writeable'),
- ('py:class', 'ops.charm._ContainerBaseDict'),
- ('py:class', 'ops.model._AddressDict'),
- ('py:class', 'ops.model._ConfigOption'),
- ('py:class', 'ops.model._ModelBackend'),
- ('py:class', 'ops.model._ModelCache'),
- ('py:class', 'ops.model._NetworkDict'),
- ('py:class', 'ops.pebble._FileLikeIO'),
- ('py:class', 'ops.pebble._IOSource'),
- ('py:class', 'ops.pebble._ServiceInfoDict'),
- ('py:class', 'ops.pebble._SystemInfoDict'),
- ('py:class', 'ops.pebble._WebSocket'),
- ('py:class', 'ops.storage.JujuStorage'),
- ('py:class', 'ops.storage.SQLiteStorage'),
- ('py:class', 'ops.testing.CharmType'),
- ('py:obj', 'ops.testing.CharmType'),
-]
+# 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'
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
-extensions = [
- 'sphinx.ext.autodoc',
- 'sphinx.ext.intersphinx',
- 'sphinx.ext.napoleon',
- 'sphinx.ext.todo',
- 'sphinx.ext.viewcode',
-
- 'custom-rst-roles',
- 'related-links',
- 'sphinx_copybutton',
- 'sphinx_design',
- 'sphinx_tabs.tabs',
+############################################################
+### General configuration
+############################################################
+
+exclude_patterns = [
+ '_build',
+ 'Thumbs.db',
+ '.DS_Store',
+ '.sphinx',
]
+exclude_patterns.extend(custom_excludes)
-rst_epilog = """
-.. _Canonical website: https://canonical.com/
-.. _reStructuredText style guide: https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide/
-.. _Sphinx reStructuredText Primer: https://tinyurl.com/rstprimer
-.. _Canonical Documentation Style Guide: https://docs.ubuntu.com/styleguide/en
-"""
+rst_epilog = '''
+.. include:: /reuse/links.txt
+'''
+if 'custom_rst_epilog' in locals():
+ rst_epilog = custom_rst_epilog
source_suffix = {
'.rst': 'restructuredtext',
+ '.md': 'markdown',
}
-# The document name of the “master” document, that is, the document
-# that contains the root toctree directive.
-master_doc = 'index'
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+if not 'conf_py_path' in html_context and 'github_folder' in html_context:
+ html_context['conf_py_path'] = html_context['github_folder']
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+# For ignoring specific links
+linkcheck_anchors_ignore_for_url = [
+ r'https://github\.com/.*'
+]
+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)
-# -- Options for HTML output -------------------------------------------------
+############################################################
+### Styling
+############################################################
# Find the current builder
-builder = "dirhtml"
+builder = 'dirhtml'
if '-b' in sys.argv:
- builder = sys.argv[sys.argv.index('-b') + 1]
+ builder = sys.argv[sys.argv.index('-b')+1]
+# Setting templates_path for epub makes the build fail
+if builder == 'dirhtml' or builder == 'html':
+ templates_path = ['.sphinx/_templates']
+ notfound_template = '404.html'
+
+# Theme configuration
html_theme = 'furo'
-html_last_updated_fmt = ""
-html_permalinks_icon = "¶"
-html_theme_options = {
- "light_css_variables": {
- "color-sidebar-background-border": "none",
- "font-stack": "Ubuntu, -apple-system, Segoe UI, Roboto, Oxygen, Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif", # noqa: E501
- "font-stack--monospace": "Ubuntu Mono, Consolas, Monaco, Courier, monospace",
- "color-foreground-primary": "#111",
- "color-foreground-secondary": "var(--color-foreground-primary)",
- "color-foreground-muted": "#333",
- "color-background-secondary": "#FFF",
- "color-background-hover": "#f2f2f2",
- "color-brand-primary": "#111",
- "color-brand-content": "#06C",
- # NOTE: this looks horrible -- commented out
- # "color-api-background": "#cdcdcd",
- "color-inline-code-background": "rgba(0,0,0,.03)",
- "color-sidebar-link-text": "#111",
- "color-sidebar-item-background--current": "#ebebeb",
- "color-sidebar-item-background--hover": "#f2f2f2",
- "toc-font-size": "var(--font-size--small)",
- "color-admonition-title-background--note": "var(--color-background-primary)",
- "color-admonition-title-background--tip": "var(--color-background-primary)",
- "color-admonition-title-background--important": "var(--color-background-primary)",
- "color-admonition-title-background--caution": "var(--color-background-primary)",
- "color-admonition-title--note": "#24598F",
- "color-admonition-title--tip": "#24598F",
- "color-admonition-title--important": "#C7162B",
- "color-admonition-title--caution": "#F99B11",
- "color-highlighted-background": "#EbEbEb",
- "color-link-underline": "var(--color-background-primary)",
- "color-link-underline--hover": "var(--color-background-primary)",
- "color-version-popup": "#772953"
- },
- "dark_css_variables": {
- "color-foreground-secondary": "var(--color-foreground-primary)",
- "color-foreground-muted": "#CDCDCD",
- "color-background-secondary": "var(--color-background-primary)",
- "color-background-hover": "#666",
- "color-brand-primary": "#fff",
- "color-brand-content": "#06C",
- "color-sidebar-link-text": "#f7f7f7",
- "color-sidebar-item-background--current": "#666",
- "color-sidebar-item-background--hover": "#333",
- "color-admonition-background": "transparent",
- "color-admonition-title-background--note": "var(--color-background-primary)",
- "color-admonition-title-background--tip": "var(--color-background-primary)",
- "color-admonition-title-background--important": "var(--color-background-primary)",
- "color-admonition-title-background--caution": "var(--color-background-primary)",
- "color-admonition-title--note": "#24598F",
- "color-admonition-title--tip": "#24598F",
- "color-admonition-title--important": "#C7162B",
- "color-admonition-title--caution": "#F99B11",
- "color-highlighted-background": "#666",
- "color-link-underline": "var(--color-background-primary)",
- "color-link-underline--hover": "var(--color-background-primary)",
- "color-version-popup": "#F29879"
- },
-}
+html_last_updated_fmt = ''
+html_permalinks_icon = '¶'
+
+if html_title == '':
+ html_theme_options = {
+ 'sidebar_hide_name': True
+ }
+
+############################################################
+### Additional files
+############################################################
+
+html_static_path = ['.sphinx/_static']
-html_static_path = ['_static']
html_css_files = [
'custom.css',
+ 'header.css',
'github_issue_links.css',
+ 'furo_colors.css'
]
+html_css_files.extend(custom_html_css_files)
-html_js_files = []
-if "github_issues" in html_context and html_context["github_issues"]:
+html_js_files = ['header-nav.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')
-
-
-# -- Options for sphinx.ext.todo ---------------------------------------------
-
-# If this is True, todo and todolist produce output, else they
-# produce nothing. The default is False.
-todo_include_todos = False
-
-
-# -- Options for sphinx.ext.autodoc ------------------------------------------
-
-# This value controls how to represents typehints. The setting takes the
-# following values:
-# 'signature' – Show typehints as its signature (default)
-# 'description' – Show typehints as content of function or method
-# 'none' – Do not show typehints
-autodoc_typehints = 'signature'
-
-# This value selects what content will be inserted into the main body of an
-# autoclass directive. The possible values are:
-# 'class' - Only the class’ docstring is inserted. This is the
-# default. You can still document __init__ as a separate method
-# using automethod or the members option to autoclass.
-# 'both' - Both the class’ and the __init__ method’s docstring are
-# concatenated and inserted.
-# 'init' - Only the __init__ method’s docstring is inserted.
-autoclass_content = 'class'
-
-# This value selects if automatically documented members are sorted
-# alphabetical (value 'alphabetical'), by member type (value
-# 'groupwise') or by source order (value 'bysource'). The default is
-# alphabetical.
-autodoc_member_order = 'alphabetical'
-
-autodoc_default_options = {
- 'members': None, # None here means "yes"
- 'undoc-members': None,
- 'show-inheritance': None,
-}
-
-
-# -- Options for sphinx.ext.intersphinx --------------------------------------
-
-# This config value contains the locations and names of other projects
-# that should be linked to in this documentation.
-intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
+html_js_files.extend(custom_html_js_files)
diff --git a/docs/custom_conf.py b/docs/custom_conf.py
new file mode 100644
index 000000000..773efba7e
--- /dev/null
+++ b/docs/custom_conf.py
@@ -0,0 +1,202 @@
+import datetime
+
+# 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 = 'Documentation starter pack'
+author = 'Canonical Group Ltd'
+
+# The title you want to display for the documentation in the sidebar.
+# You might want to include a version number here.
+# To not display any title, set this option to an empty string.
+html_title = project + ' documentation'
+
+# 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://canonical-starter-pack.readthedocs-hosted.com/'
+# 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/253da317-image-document-ubuntudocs.svg'
+
+# 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': 'documentation.ubuntu.com',
+
+ # 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',
+
+ # Change to the Mattermost channel you want to link to
+ # (use an empty value if you don't want to link)
+ 'mattermost': 'https://chat.canonical.com/canonical/channels/documentation',
+
+ # Change to the GitHub URL for your project
+ 'github_url': 'https://github.com/canonical/starter-pack',
+
+ # 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': '/',
+
+ # 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': "none"
+}
+
+# If your project is on documentation.ubuntu.com, specify the project
+# slug (for example, "lxd") here.
+slug = ""
+
+############################################################
+### 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.
+redirects = {}
+
+############################################################
+### Link checker exceptions
+############################################################
+
+# Links to ignore when checking links
+linkcheck_ignore = [
+ 'http://127.0.0.1:8000'
+ ]
+
+# Pages on which to ignore anchors
+# (This list will be appended to linkcheck_anchors_ignore_for_url)
+custom_linkcheck_anchors_ignore_for_url = []
+
+############################################################
+### Additions to default configuration
+############################################################
+
+## The following settings are appended to the default configuration.
+## Use them to extend the default functionality.
+# NOTE: 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'
+ ]
+
+# 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 = []
+
+# Add files or directories that should be excluded from processing.
+custom_excludes = [
+ 'doc-cheat-sheet*',
+ ]
+
+# Add CSS files (located in .sphinx/_static/)
+custom_html_css_files = []
+
+# Add JavaScript files (located in .sphinx/_static/)
+custom_html_js_files = []
+
+## 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 = []
+
+############################################################
+### Additional configuration
+############################################################
+
+## Add any configuration that is not covered by the common conf.py file.
+
+# Define a :center: role that can be used to center the content of table cells.
+rst_prolog = '''
+.. role:: center
+ :class: align-center
+'''
 }})
+