From 6fe90668986075708a7036b450a97c3486801c63 Mon Sep 17 00:00:00 2001 From: Jean-Baptiste Lallement Date: Fri, 3 Nov 2023 10:49:58 +0200 Subject: [PATCH] Update documentation framework --- docs/.custom_wordlist.txt | 98 +++++++++++++++++ docs/.gitignore | 3 +- docs/.sphinx/_static/furo_colors.css | 88 +++++++++++++++ docs/.sphinx/_static/github_issue_links.js | 8 ++ docs/.sphinx/_templates/base.html | 5 + docs/.sphinx/_templates/footer.html | 61 ++++++----- docs/.sphinx/requirements.txt | 17 +-- docs/.sphinx/spellingcheck.yaml | 2 + docs/.wordlist.txt | 119 ++++----------------- docs/Makefile | 76 ++++--------- docs/conf.py | 74 +++---------- docs/custom_conf.py | 52 +++++++-- 12 files changed, 345 insertions(+), 258 deletions(-) create mode 100644 docs/.custom_wordlist.txt create mode 100644 docs/.sphinx/_static/furo_colors.css diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt new file mode 100644 index 000000000..0e2ad98dd --- /dev/null +++ b/docs/.custom_wordlist.txt @@ -0,0 +1,98 @@ +Acknowledgements +adml +ADML +admx +ADMX +adsys +ADSys +adsysctl +adsysd +adwatchd +apparmor +AppArmor +AppArmor's +autocompletion +autoenroll +autoenrollment +autoload +backend +backends +CAs +CEP +CES +changelog +compinit +config +constructiveCAs +CSR +dconf +dir +Dropdown +enrolment +erroring +executables +fpath +FQDN +GDM +GPL +GPO +gpolist +GPOs +GPT +GSettings +GVfs +html +https +idempotency +IIS +incrementation +incrementing +infos +ini +ip +Jira +kerberos +Kerberos +LDAP +lifecycle +LTS +MacOS +macOS +multiline +OpenLDAP +OU +OUs +polkit +powershell +PowerShell +readthedocs +runscripts +sss +sssd +SSSD +subcommands +subdirectory +subprofile +subprofiles +sudo +syntaxes +systemd +systemd's +sysvol +TDB +TODO +toolset +Transactional +txt +ubuntu +Unix +unmonitoring +unmount +unmounting +Unmounting +unticking +vendoring +Winbind +yaml +zsh +zshrc diff --git a/docs/.gitignore b/docs/.gitignore index c8f8ee69f..d261ebfc7 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,7 +1,8 @@ /*env*/ -.sphinx/venv +.sphinx/venv/ .sphinx/warnings.txt .sphinx/.wordlist.dic +.sphinx/.doctrees/ _build .DS_Store __pycache__ diff --git a/docs/.sphinx/_static/furo_colors.css b/docs/.sphinx/_static/furo_colors.css new file mode 100644 index 000000000..ffc36cbc8 --- /dev/null +++ b/docs/.sphinx/_static/furo_colors.css @@ -0,0 +1,88 @@ +body { + --color-code-background: #f8f8f8; + --color-code-foreground: black; + --font-stack: Ubuntu, -apple-system, Segoe UI, Roboto, Oxygen, Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif; + --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; + --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; +} + +@media not print { + body[data-theme="dark"] { + --color-code-background: #202020; + --color-code-foreground: #d0d0d0; + --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; + } + @media (prefers-color-scheme: dark) { + body:not([data-theme="light"]) { + --color-code-background: #202020; + --color-code-foreground: #d0d0d0; + --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; + } + } +} diff --git a/docs/.sphinx/_static/github_issue_links.js b/docs/.sphinx/_static/github_issue_links.js index 980609cd0..f0706038b 100644 --- a/docs/.sphinx/_static/github_issue_links.js +++ b/docs/.sphinx/_static/github_issue_links.js @@ -1,4 +1,12 @@ +// if we already have an onload function, save that one +var prev_handler = window.onload; + window.onload = function() { + // call the previous onload function + if (prev_handler) { + prev_handler(); + } + const link = document.createElement("a"); link.classList.add("muted-link"); link.classList.add("github-issue-link"); diff --git a/docs/.sphinx/_templates/base.html b/docs/.sphinx/_templates/base.html index 62ffe6b8c..33081547c 100644 --- a/docs/.sphinx/_templates/base.html +++ b/docs/.sphinx/_templates/base.html @@ -5,3 +5,8 @@ const github_url = "{{ github_url }}"; {% endblock theme_scripts %} + +{# ru-fu: don't include the color variables from the conf.py file, but use a + separate CSS file to save space #} +{% block theme_styles %} +{% endblock theme_styles %} diff --git a/docs/.sphinx/_templates/footer.html b/docs/.sphinx/_templates/footer.html index 759448687..f13cb6314 100644 --- a/docs/.sphinx/_templates/footer.html +++ b/docs/.sphinx/_templates/footer.html @@ -1,31 +1,40 @@ -{# ru-fu: copied from Furo, with modifications as stated below #} +{# ru-fu: copied from Furo, with modifications as stated below. Modifications are marked 'mod:'. #}
- {% if next -%} - -
-
- {{ _("Next") }} + {# mod: Per-page navigation #} + {% if meta %} + {% if 'sequential_nav' in meta %} + {% set sequential_nav = meta.sequential_nav %} + {% endif %} + {% endif %} + {# mod: Conditional wrappers to control page navigation buttons #} + {% if sequential_nav != "none" -%} + {% if next and (sequential_nav == "next" or sequential_nav == "both") -%} + +
+
+ {{ _("Next") }} +
+
{{ next.title }}
-
{{ next.title }}
-
- - - {%- endif %} - {% if prev -%} - - -
-
- {{ _("Previous") }} + + + {%- endif %} + {% if prev and (sequential_nav == "prev" or sequential_nav == "both") -%} + + +
+
+ {{ _("Previous") }} +
+ {% if prev.link == pathto(master_doc) %} +
{{ _("Home") }}
+ {% else %} +
{{ prev.title }}
+ {% endif %}
- {% if prev.link == pathto(master_doc) %} -
{{ _("Home") }}
- {% else %} -
{{ prev.title }}
- {% endif %} -
- + + {%- endif %} {%- endif %}
@@ -44,7 +53,7 @@
{%- endif %} - {# ru-fu: removed "Made with" #} + {# mod: removed "Made with" #} {%- if last_updated -%}
@@ -63,7 +72,7 @@
- {# ru-fu: replaced RTD icons with our links #} + {# mod: replaced RTD icons with our links #} {% if discourse %}
diff --git a/docs/.sphinx/requirements.txt b/docs/.sphinx/requirements.txt index d6f37e04b..f5a1d8c38 100644 --- a/docs/.sphinx/requirements.txt +++ b/docs/.sphinx/requirements.txt @@ -1,13 +1,14 @@ +furo +linkify-it-py +lxd-sphinx-extensions +myst-parser +pyspelling sphinx sphinx-autobuild +sphinx-copybutton sphinx-design -furo -sphinx-tabs +sphinx-notfound-page sphinx-reredirects -pyspelling -sphinxext-opengraph -lxd-sphinx-extensions -sphinx-copybutton -myst-parser +sphinx-tabs sphinxcontrib-jquery -sphinx-notfound-page +sphinxext-opengraph diff --git a/docs/.sphinx/spellingcheck.yaml b/docs/.sphinx/spellingcheck.yaml index b007590ea..5d85d157a 100644 --- a/docs/.sphinx/spellingcheck.yaml +++ b/docs/.sphinx/spellingcheck.yaml @@ -6,6 +6,7 @@ matrix: dictionary: wordlists: - .wordlist.txt + - .custom_wordlist.txt output: .sphinx/.wordlist.dic sources: - _build/**/*.html @@ -22,6 +23,7 @@ matrix: - link - title - div.relatedlinks + - strong.command - div.visually-hidden - img - a.p-navigation__link diff --git a/docs/.wordlist.txt b/docs/.wordlist.txt index 4a57c5403..aa3251f75 100644 --- a/docs/.wordlist.txt +++ b/docs/.wordlist.txt @@ -1,115 +1,38 @@ -Acknowledgements -adml -ADML -admx -ADMX -adsys -ADSys -adsysctl -adsysd -adwatchd +addons +API APIs -apparmor -AppArmor -AppArmor's -autocompletion -autoenroll -autoenrollment -autoload -backend -backends -CAs -CEP -CES -changelog +balancer +Charmhub CLI -compinit -config -constructiveCAs -CSR -dconf +dropdown Diátaxis -dir -Dropdown -enrolment -erroring -executables +EBS +EKS favicon -fpath -FQDN -GDM -GPL -GPO -gpolist -GPOs -GPT -GSettings -GVfs -html -https -idempotency -IIS -incrementation -incrementing -infos -ini +Furo +Grafana +IAM installable -ip -Jira -kerberos -Kerberos -LDAP -lifecycle -LTS -MacOS -macOS +JSON +Juju +Kubernetes +Kubeflow Makefile -multiline MyST namespace -OpenLDAP -OU -OUs +namespaces +NodePort +observability +OLM Permalink -polkit -powershell -PowerShell pre ReadMe -readthedocs reST reStructuredText RTD -runscripts -sss -sssd -SSSD -subcommands subdirectories -subdirectory -subprofile -subprofiles subtree -sudo -syntaxes -systemd -systemd's -sysvol -TDB -TODO -toolset -Transactional -txt -ubuntu +subfolders UI -Unix -unmonitoring -unmount -unmounting -Unmounting -unticking -vendoring -Winbind -yaml -zsh -zshrc +VM +YAML diff --git a/docs/Makefile b/docs/Makefile index c85dcc5c2..a76d8aab9 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -3,7 +3,7 @@ # You can set these variables from the command line, and also # from the environment for the first two. -SPHINXOPTS ?= +SPHINXOPTS ?= -c . -d .sphinx/.doctrees SPHINXBUILD ?= sphinx-build SPHINXDIR = .sphinx SOURCEDIR = . @@ -11,12 +11,12 @@ BUILDDIR = _build VENVDIR = $(SPHINXDIR)/venv VENV = $(VENVDIR)/bin/activate +.PHONY: help woke-install install run html epub serve clean clean-doc \ + spelling linkcheck woke Makefile # Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help +help: $(VENVDIR) + @. $(VENV); $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) # Explicit target avoids fall-through to the "Makefile" target. $(SPHINXDIR)/requirements.txt: @@ -26,7 +26,12 @@ $(SPHINXDIR)/requirements.txt: $(VENVDIR): $(SPHINXDIR)/requirements.txt @echo "... setting up virtualenv" python3 -m venv $(VENVDIR) - . $(VENV); pip install --upgrade -r $(SPHINXDIR)/requirements.txt + . $(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 @echo "\n" \ "--------------------------------------------------------------- \n" \ "* watch, build and serve the documentation: make run \n" \ @@ -34,88 +39,51 @@ $(VENVDIR): $(SPHINXDIR)/requirements.txt "* only serve: make serve \n" \ "* clean built doc files: make clean-doc \n" \ "* clean full environment: make clean \n" \ + "* check links: make linkcheck \n" \ "* check spelling: make spelling \n" \ "* check inclusive language: make woke \n" \ "* other possible targets: make \n" \ "--------------------------------------------------------------- \n" @touch $(VENVDIR) - woke-install: @type woke >/dev/null 2>&1 || \ - { echo "Installing \"woke\" snap... \n"; sudo snap install woke; } - -.PHONY: woke-install - + { echo "Installing \"woke\" snap... \n"; sudo snap install woke; } install: $(VENVDIR) woke-install -.PHONY: install - - run: install - . $(VENV); sphinx-autobuild -c . -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" - -.PHONY: run + . $(VENV); sphinx-autobuild -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) # Doesn't depend on $(BUILDDIR) to rebuild properly at every run. html: install - . $(VENV); $(SPHINXBUILD) -c . -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" \ - -w .sphinx/warnings.txt - -.PHONY: html - + . $(VENV); $(SPHINXBUILD) -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w .sphinx/warnings.txt $(SPHINXOPTS) epub: install - . $(VENV); $(SPHINXBUILD) -c . -b epub "$(SOURCEDIR)" "$(BUILDDIR)" \ - -w .sphinx/warnings.txt - -.PHONY: epub - + . $(VENV); $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w .sphinx/warnings.txt $(SPHINXOPTS) serve: html cd "$(BUILDDIR)"; python3 -m http.server 8000 -.PHONY: serve - - clean: clean-doc - @test ! -e "$(VENVDIR)" -o \ - -d "$(VENVDIR)" -a "$(abspath $(VENVDIR))" != "$(VENVDIR)" + @test ! -e "$(VENVDIR)" -o -d "$(VENVDIR)" -a "$(abspath $(VENVDIR))" != "$(VENVDIR)" rm -rf $(VENVDIR) - -.PHONY: clean - + rm -rf .sphinx/.doctrees clean-doc: git clean -fx "$(BUILDDIR)" -.PHONY: clean-doc - - spelling: html . $(VENV) ; python3 -m pyspelling -c .sphinx/spellingcheck.yaml -.PHONY: spelling - - linkcheck: install - . $(VENV) ; $(SPHINXBUILD) -c . -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" - -.PHONY: linkcheck - + . $(VENV) ; $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) woke: woke-install - woke *.rst **/*.rst \ - -c https://github.com/canonical/Inclusive-naming/raw/main/config.yml - -.PHONY: woke - + woke *.rst **/*.rst --exit-1-on-failure \ + -c https://github.com/canonical/Inclusive-naming/raw/main/config.yml # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile - . $(VENV); \ - $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: Makefile + . $(VENV); $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py index 50752c569..3292d8121 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -36,11 +36,13 @@ # Additional MyST syntax myst_enable_extensions = [ 'substitution', - 'deflist' + 'deflist', + 'linkify' ] +myst_enable_extensions.extend(custom_myst_extensions) # Used for related links -if 'discourse' in html_context: +if not 'discourse_prefix' in html_context and 'discourse' in html_context: html_context['discourse_prefix'] = html_context['discourse'] + '/t/' # The default for notfound_urls_prefix usually works, but not for @@ -67,7 +69,6 @@ 'Thumbs.db', '.DS_Store', '.sphinx', - 'doc-cheat-sheet*', ] exclude_patterns.extend(custom_excludes) @@ -89,9 +90,11 @@ linkcheck_anchors_ignore_for_url = [ r'https://github\.com/.*' ] +linkcheck_anchors_ignore_for_url.extend(custom_linkcheck_anchors_ignore_for_url) -# Some Ubuntu links are unstable -linkcheck_retries = 10 +# Tags cannot be added directly in custom_conf.py, so add them here +for tag in custom_tags: + tags.add(tag) ############################################################ ### Styling @@ -110,61 +113,11 @@ html_theme = 'furo' html_last_updated_fmt = '' html_permalinks_icon = '¶' -html_theme_options = { - 'light_css_variables': { - 'font-stack': 'Ubuntu, -apple-system, Segoe UI, Roboto, Oxygen, Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif', - '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', - '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' - }, -} + +if html_title == '': + html_theme_options = { + 'sidebar_hide_name': True + } ############################################################ ### Additional files @@ -176,6 +129,7 @@ 'custom.css', 'header.css', 'github_issue_links.css', + 'furo_colors.css' ] html_css_files.extend(custom_html_css_files) diff --git a/docs/custom_conf.py b/docs/custom_conf.py index 205a3a617..4f947aa4d 100644 --- a/docs/custom_conf.py +++ b/docs/custom_conf.py @@ -9,6 +9,10 @@ # # 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 @@ -18,8 +22,10 @@ project = 'Active Directory GPO support' author = 'Canonical Group Ltd' -# Uncomment if your product uses release numbers -# release = '0.13.0' +# 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. # @@ -37,26 +43,33 @@ copyright = '%s, %s' % (datetime.date.today().year, author) -## Open Graph configuration - defines what is displayed in the website preview -# The URL of the documentation output +## 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) 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 -# An image or logo that is used in the preview +# 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 favicon for your product (default is the circle of friends) +# 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 your product website (without "https://") - 'product_page': 'github.com/ubuntu/adsys', + # 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 to ".sphinx/_static" and change the path - # here (start with "_static"), default is the circle of friends + # 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 @@ -76,7 +89,11 @@ # 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' + '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 @@ -102,6 +119,12 @@ '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 ############################################################ @@ -112,6 +135,9 @@ # Add extensions custom_extensions = [] +# Add MyST extensions +custom_myst_extensions = [] + # Add files or directories that should be excluded from processing. custom_excludes = [] @@ -132,6 +158,10 @@ # 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 ############################################################