From 28b2fb2282643992665331fe179bbc3dcbbee760 Mon Sep 17 00:00:00 2001 From: jahn-junior Date: Tue, 21 Apr 2026 13:00:50 -0700 Subject: [PATCH 01/10] chore!: remove docs and default configuration --- docs/conf.py | 177 +--- docs/contribute/index.rst | 5 - docs/contribute/test-ulwazi-theme.md | 237 ----- docs/explanation/assets/extensions.png | Bin 60993 -> 0 bytes .../assets/python-starter-pack.png | Bin 13697 -> 0 bytes docs/explanation/assets/rtd-build.png | Bin 24574 -> 0 bytes docs/explanation/assets/sphinx.png | Bin 17713 -> 0 bytes docs/explanation/assets/third-party.png | Bin 32925 -> 0 bytes docs/explanation/build.rst | 78 -- docs/explanation/components.rst | 137 --- docs/explanation/index.rst | 16 - docs/explanation/sitemaps.rst | 187 ---- docs/how-to/assets/openapi._rst | 22 - docs/how-to/assets/openapi.yaml | 24 - .../troubleshoot-stable-zombie-version.png | Bin 70434 -> 0 bytes docs/how-to/build-and-preview.rst | 167 --- docs/how-to/configure-your-project.rst | 179 ---- docs/how-to/contributing-myst.md | 228 ---- docs/how-to/contributing.rst | 330 ------ docs/how-to/index.rst | 39 - .../add-documentation-testing.rst | 330 ------ .../bridge-project-and-docs-builds.rst | 353 ------- .../custom-html-templates.md | 156 --- .../optional-customisation/customise-pdf.rst | 270 ----- .../enable-google-analytics.rst | 126 --- .../external-referencing-intersphinx.rst | 97 -- docs/how-to/optional-customisation/index.rst | 23 - .../interactive-tables.rst | 43 - .../mermaid-diagrams.md | 125 --- .../openapi-specifications.rst | 116 -- .../python-docstrings.md | 100 -- docs/how-to/publish-on-rtd.rst | 63 -- docs/how-to/troubleshooting.rst | 63 -- docs/how-to/update-starter-packs/index.rst | 47 - .../legacy-starter-pack.rst | 216 ---- .../update-starter-packs/new-starter-pack.rst | 164 --- docs/index.rst | 59 +- docs/redirects.txt | 39 - docs/reference/automatic_checks.rst | 108 -- .../automatic_checks_accessibility.rst | 41 - .../automatic_checks_inclusivelanguage.rst | 80 -- docs/reference/automatic_checks_links.rst | 20 - docs/reference/automatic_checks_linting.rst | 21 - .../automatic_checks_removed-url-check.rst | 14 - docs/reference/automatic_checks_spelling.rst | 38 - .../reference/automatic_checks_styleguide.rst | 112 -- docs/reference/default-extensions.rst | 85 -- docs/reference/include.txt | 3 - docs/reference/index.rst | 20 +- docs/reference/myst-syntax.md | 977 ----------------- docs/reference/rst-syntax.rst | 989 ------------------ docs/release-notes/1.4.rst | 86 -- docs/release-notes/1.5.rst | 176 ---- docs/release-notes/1.6.rst | 133 --- .../assets/release-commit-history.svg | 1 - docs/release-notes/index.rst | 45 - docs/set-up-a-new-project.rst | 139 --- docs/tutorials/index.rst | 4 + 58 files changed, 83 insertions(+), 7225 deletions(-) delete mode 100644 docs/contribute/test-ulwazi-theme.md delete mode 100644 docs/explanation/assets/extensions.png delete mode 100644 docs/explanation/assets/python-starter-pack.png delete mode 100644 docs/explanation/assets/rtd-build.png delete mode 100644 docs/explanation/assets/sphinx.png delete mode 100644 docs/explanation/assets/third-party.png delete mode 100644 docs/explanation/build.rst delete mode 100644 docs/explanation/components.rst delete mode 100644 docs/explanation/sitemaps.rst delete mode 100644 docs/how-to/assets/openapi._rst delete mode 100644 docs/how-to/assets/openapi.yaml delete mode 100644 docs/how-to/assets/troubleshoot-stable-zombie-version.png delete mode 100644 docs/how-to/build-and-preview.rst delete mode 100644 docs/how-to/configure-your-project.rst delete mode 100644 docs/how-to/contributing-myst.md delete mode 100644 docs/how-to/contributing.rst delete mode 100644 docs/how-to/optional-customisation/add-documentation-testing.rst delete mode 100644 docs/how-to/optional-customisation/bridge-project-and-docs-builds.rst delete mode 100644 docs/how-to/optional-customisation/custom-html-templates.md delete mode 100644 docs/how-to/optional-customisation/customise-pdf.rst delete mode 100644 docs/how-to/optional-customisation/enable-google-analytics.rst delete mode 100644 docs/how-to/optional-customisation/external-referencing-intersphinx.rst delete mode 100644 docs/how-to/optional-customisation/index.rst delete mode 100644 docs/how-to/optional-customisation/interactive-tables.rst delete mode 100644 docs/how-to/optional-customisation/mermaid-diagrams.md delete mode 100644 docs/how-to/optional-customisation/openapi-specifications.rst delete mode 100644 docs/how-to/optional-customisation/python-docstrings.md delete mode 100644 docs/how-to/publish-on-rtd.rst delete mode 100644 docs/how-to/troubleshooting.rst delete mode 100644 docs/how-to/update-starter-packs/index.rst delete mode 100644 docs/how-to/update-starter-packs/legacy-starter-pack.rst delete mode 100644 docs/how-to/update-starter-packs/new-starter-pack.rst delete mode 100644 docs/reference/automatic_checks.rst delete mode 100644 docs/reference/automatic_checks_accessibility.rst delete mode 100644 docs/reference/automatic_checks_inclusivelanguage.rst delete mode 100644 docs/reference/automatic_checks_links.rst delete mode 100644 docs/reference/automatic_checks_linting.rst delete mode 100644 docs/reference/automatic_checks_removed-url-check.rst delete mode 100644 docs/reference/automatic_checks_spelling.rst delete mode 100644 docs/reference/automatic_checks_styleguide.rst delete mode 100644 docs/reference/default-extensions.rst delete mode 100644 docs/reference/include.txt delete mode 100644 docs/reference/myst-syntax.md delete mode 100644 docs/reference/rst-syntax.rst delete mode 100644 docs/release-notes/1.4.rst delete mode 100644 docs/release-notes/1.5.rst delete mode 100644 docs/release-notes/1.6.rst delete mode 100644 docs/release-notes/assets/release-commit-history.svg delete mode 100644 docs/set-up-a-new-project.rst create mode 100644 docs/tutorials/index.rst diff --git a/docs/conf.py b/docs/conf.py index b0aad1f5..9766104a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,6 +1,5 @@ import datetime import os -import yaml # Configuration for the Sphinx documentation builder. # All configuration specific to your project should be done in this file. @@ -11,8 +10,8 @@ # A complete list of built-in Sphinx configuration values: # https://www.sphinx-doc.org/en/master/usage/configuration.html # -# Our starter pack uses the custom Canonical Sphinx extension -# to keep all documentation based on it consistent and on brand: +# The Starter Pack uses the Canonical Sphinx theme to keep +# all documentation consistent and on brand: # https://github.com/canonical/canonical-sphinx @@ -22,146 +21,112 @@ # Project name # -# TODO: Update with the official name of your project or product +# TODO: Update with the official name of your project or product (e.g., "Ubuntu Server")_ +project = "" -project = "Documentation starter pack" -author = "Canonical Ltd." - -# The year in the copyright statement defaults to the current year, so -# individual document versions show when they were built. -# TODO: If the date must be a range, like in a software license, replace -# 2026 with the starting year of development and use: -# -# copyright = f"2026-{datetime.date.today().year}" +author = "Canonical" +# The year in the copyright statement copyright = f"{datetime.date.today().year}" -# Sidebar documentation title; best kept reasonably short +# Sidebar documentation title # -# TODO: To include a version number, add it here (hardcoded or automated). -# -# TODO: To disable the title, set to an empty string. - +# To disable the title, set it to an empty string. html_title = project + " documentation" - # Documentation website URL -# -# TODO: Update with the official URL of your docs or leave empty if unsure. -# -# NOTE: The Open Graph Protocol (OGP) enhances page display in a social graph -# and is used by social media platforms; see https://ogp.me/ - -ogp_site_url = "https://canonical-starter-pack.readthedocs-hosted.com/" +ogp_site_url = os.environ.get("READTHEDOCS_CANONICAL_URL", "/") # Preview name of the documentation website # -# TODO: To use a different name for the project in previews, update as needed. - +# TODO: To use a different name for the project in previews, update the next line. ogp_site_name = project # Preview image URL # -# TODO: To customise the preview image, update as needed. - +# TODO: To customise the preview image, update the next line. ogp_image = "https://assets.ubuntu.com/v1/cc828679-docs_illustration.svg" -# Product favicon; shown in bookmarks, browser tabs, etc. - -# TODO: To customise the favicon, uncomment and update as needed. - -# html_favicon = '.sphinx/_static/favicon.png' +# Product favicon +# +# TODO: To customise the favicon, uncomment and update the next line. +# html_favicon = ".sphinx/_static/favicon.png" # Dictionary of values to pass into the Sphinx context for all pages: # https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_context - html_context = { # Product page URL; can be different from product docs URL # - # TODO: Change to your product website URL, - # dropping the 'https://' prefix, e.g. 'ubuntu.com/lxd'. + # TODO: Change to your product website URL, dropping the 'https://' prefix (e.g., + # 'ubuntu.com/lxd'). # - # TODO: If there's no such website, - # remove the {{ product_page }} link from the page header template - # (usually .sphinx/_templates/header.html; also, see README.rst). - "product_page": "documentation.ubuntu.com", + # TODO: If there's no such website, remove the {{ product_page }} link from the + # .sphinx/_templates/header.html file. + "product_page": "", + # Product tag image; the orange part of your logo, shown in the page header # # TODO: To add a tag image, uncomment and update as needed. # 'product_tag': '_static/tag.png', + # Your Discourse instance URL # # TODO: Change to your Discourse instance URL or leave empty. - # - # NOTE: If set, adding ':discourse: 123' to an .rst file - # will add a link to Discourse topic 123 at the bottom of the page. - "discourse": "https://discourse.ubuntu.com", + "discourse": "", + # Your Mattermost channel URL # # TODO: Change to your Mattermost channel URL or leave empty. - "mattermost": "https://chat.canonical.com/canonical/channels/documentation", + "mattermost": "", + # Your Matrix channel URL # # TODO: Change to your Matrix channel URL or leave empty. - "matrix": "https://matrix.to/#/#documentation:ubuntu.com", + "matrix": "", + # Your documentation GitHub repository URL # # TODO: Change to your documentation GitHub repository URL or leave empty. # # NOTE: If set, links for viewing the documentation source files # and creating GitHub issues are added at the bottom of each page. - "github_url": "https://github.com/canonical/sphinx-docs-starter-pack", + "github_url": "", + # Docs branch in the repo; used in links for viewing the source files - # - # TODO: To customise the branch, uncomment and update as needed. 'repo_default_branch': 'main', + # Docs location in the repo; used in links for viewing the source files - # - - - # TODO: To customise the directory, uncomment and update as needed. "repo_folder": "/docs/", + # TODO: To enable or disable the Previous / Next buttons at the bottom of pages # Valid options: none, prev, next, both - # "sequential_nav": "both", + # "sequential_nav": "", + # TODO: To enable listing contributors on individual pages, set to True "display_contributors": False, # Required for feedback button 'github_issues': 'enabled', - # Inherit the author value + # Passes the top-level 'author' value to the theme "author": author, - # The starter pack uses CC-BY-SA as the license - # - # TODO: If your docs need another license, specify it instead of 'CC-BY-SA'. - # For the name, we recommend using the standard shorthand identifier from - # https://spdx.org/licenses - # - # For the URL, link directly to the license statement, typically found on - # the product's home page or in its GitHub project. - # - # TODO: If your documentation is a part of the code repository of your project, - # it inherits the code license instead; specify it instead of 'CC-BY-SA'. - + # Documentation license information "license": { - "name": "CC-BY-SA-3.0", - "url": "https://github.com/canonical/sphinx-docs-starter-pack/blob/main/LICENSE", + # TODO: Specify your project's license. + # For the name, we recommend using the standard shorthand identifier from + # https://spdx.org/licenses + "name": "", + + # TODO: Link directly to your project's license statement. + "url": "", }, } -html_extra_path = [] - -# Allow opt-in build of the OpenAPI "Hello" example so docs stay clean by default. -if os.getenv("OPENAPI", ""): - tags.add("openapi") - html_extra_path.append("how-to/assets/openapi.yaml") - # TODO: To enable the edit button on pages, uncomment and change the link to a # public repository on GitHub or Launchpad. Any of the following link domains # are accepted: @@ -173,11 +138,10 @@ # 'source_edit_link': 'https://github.com/canonical/sphinx-docs-starter-pack', # } -# Project slug; see https://meta.discourse.org/t/what-is-category-slug/87897 +# Project slug # -# TODO: If your documentation is hosted on https://docs.ubuntu.com/, +# TODO: If your documentation is hosted on https://documentation.ubuntu.com/, # uncomment and update as needed. - # slug = '' ####################### @@ -185,28 +149,21 @@ ####################### # Use RTD canonical URL to ensure duplicate pages have a specific canonical URL - html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "/") # sphinx-sitemap uses html_baseurl 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/', ] -# TODO: 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 # ################################ @@ -236,9 +193,6 @@ ########################### # A regex list of URLs that are ignored by 'make linkcheck' -# -# TODO: Remove or adjust the ACME entry after you update the contributing guide - linkcheck_ignore = [ "http://127.0.0.1:8000", "https://github.com", @@ -250,11 +204,9 @@ # A regex list of URLs where anchors are ignored by 'make linkcheck' - linkcheck_anchors_ignore_for_url = [r"https://github\.com/.*"] -# give linkcheck multiple tries on failure -# linkcheck_timeout = 30 +# Give linkcheck multiple tries on failure linkcheck_retries = 3 ######################## @@ -265,16 +217,15 @@ # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html # # NOTE: By default, the following MyST extensions are enabled: -# substitution, deflist, linkify - +# - substitution +# - deflist +# - linkify +# # myst_enable_extensions = set() # Custom Sphinx extensions; see # https://www.sphinx-doc.org/en/master/usage/extensions/index.html - -# NOTE: The canonical_sphinx extension is required for the starter pack. - extensions = [ "canonical_sphinx", "notfound.extension", @@ -299,7 +250,6 @@ ] # Excludes files or directories from processing - exclude_patterns = [ "doc-cheat-sheet*", ".venv*", @@ -320,16 +270,15 @@ # Specifies a reST snippet to be appended to each .rst file - rst_epilog = """ .. include:: /reuse/links.txt .. include:: /reuse/substitutions.txt """ + # Feedback button at the top; enabled by default # -# TODO: To disable the button, uncomment this. - +# TODO: To disable the button, uncomment the next line. # disable_feedback_button = True @@ -349,7 +298,6 @@ # Specifies a reST snippet to be prepended to each .rst file # This defines a :center: role that centers table cell content. # This defines a :h2: role that styles content for use with PDF generation. - rst_prolog = """ .. role:: center :class: align-center @@ -361,19 +309,8 @@ :class: vale-ignore """ -# Workaround for https://github.com/canonical/canonical-sphinx/issues/34 - -if "discourse_prefix" not in html_context and "discourse" in html_context: - html_context["discourse_prefix"] = f"{html_context['discourse']}/t/" - -# Workaround for substitutions.yaml - -if os.path.exists('./reuse/substitutions.yaml'): - with open('./reuse/substitutions.yaml', 'r') as fd: - myst_substitutions = yaml.safe_load(fd.read()) - -# Add configuration for intersphinx mapping -# Map only the Sphinx documentation sets that you need to link to from your docs set. -intersphinx_mapping = { - 'sphinxcontrib-mermaid': ('https://sphinxcontrib-mermaid-demo.readthedocs.io/en/latest', None) -} +# Configuration for Intersphinx mapping +# +# intersphinx_mapping = { +# "snap": ("https://snapcraft.io/docs/", None), +# } diff --git a/docs/contribute/index.rst b/docs/contribute/index.rst index 47504e5c..aa76b710 100644 --- a/docs/contribute/index.rst +++ b/docs/contribute/index.rst @@ -2,8 +2,3 @@ Contribute ========== - -.. toctree:: - :maxdepth: 1 - - Test the Ulwazi theme \ No newline at end of file diff --git a/docs/contribute/test-ulwazi-theme.md b/docs/contribute/test-ulwazi-theme.md deleted file mode 100644 index b185a0ef..00000000 --- a/docs/contribute/test-ulwazi-theme.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -myst: - html_meta: - description: How to test the Ulwazi theme in a documentation project based on Canonical's Sphinx Starter Pack. -relatedlinks: "[Ulwazi on PyPI](https://pypi.org/project/ulwazi), [Vanilla](https://vanillaframework.org), [sphinx-basic-ng](https://github.com/pradyunsg/sphinx-basic-ng)" ---- - -(how-to-test-ulwazi-theme)= - -# Test the Ulwazi theme - -Ulwazi is a Sphinx theme built on Vanilla, with the base layout and functionality derived from sphinx-basic-ng. - -This guide outlines the steps required to use the Ulwazi theme in your Sphinx documentation project. - -## Update the dependencies - -In your project's Python requirements, replace the canonical-sphinx package with Ulwazi and its dependencies. The minimum set is: - -```{code-block} text -:caption: requirements.txt - -sphinx -build -sphinx-autobuild -canonical-sphinx-config @ git+https://github.com/Canonical/canonical-sphinx-config.git@main -myst-parser~=4.0 -sphinx-basic-ng -sphinxcontrib-jquery -beautifulsoup4 -packaging -sphinxcontrib-svg2pdfconverter[CairoSVG] -sphinx-last-updated-by-git -sphinx-sitemap -ulwazi -``` - -## Update the configuration - -This is the most important and tricky part -- updating the project configuration. A reference `conf.py` with all the required configuration and TODO markers is provided in the Ulwazi repository as [`default-conf.py`](https://github.com/canonical/ulwazi/blob/main/docs/default-conf.py). Copy it as the starting point for a new documentation set, or use it as a checklist when migrating an existing one. - -### Set the theme - -Tell Sphinx to use Ulwazi as the theme: - -```{code-block} python -:caption: conf\.py - -html_theme = "ulwazi" -``` - -### Update the extensions - -In the list of extensions, replace canonical-sphinx with Ulwazi, and its dependencies: - -```{code-block} diff -:caption: extensions in conf\.py - --"canonical-sphinx~=0.6" -+"ulwazi" -+"sphinx_terminal", -+"canonical_sphinx_config", -+"myst_parser", -+"sphinxcontrib.jquery", -``` - -If you need PDF output, add `sphinx_modern_pdf_style` to the list. - -This is only a partial list. Your project may require additional extensions beyond those listed here. - -### Add the required variables - -Add and fill the following variables immediately before `html_context = {`: - -```python -# TODO: Adjust to point to the repository where your documentation source files -# are stored. - -github_repo = - -# TODO: Select the default syntax for docs source files. -# This is for a fallback view/edit source code buttons. - -default_source_extension = ".md" - -# TODO: Change to your product website URL, -# dropping the 'https://' prefix, e.g. 'ubuntu.com/lxd'. - -product_page = -``` - -If your project is written in reST, set `default_source_extension` to `".rst"`. - -### Update the HTML context - -You need to make several updates to the `html_context` dictionary. -For an example of all the changes, see the [Charmed Apache Kafka Ulwazi PR](https://github.com/canonical/kafka-operator/pull/444/files#diff-85933aa74a2d66c3e4dcdf7a9ad8397f5a7971080d34ef1108296a7c6b69e7e3). - -The code snippets in this section might not match the exact layout of `html_context` in your `conf.py`. - -Add these new variables, including the top-level variables you declared earlier: - -```{code-block} python -:caption: html_context in conf\.py - -"product_page": product_page, # was: "your-product.example.com" -"github_url": github_repo, # was: "https://github.com/your-org/your-repo" -"license": { - "name": "Apache-2.0", # TODO: set your license - "url": github_repo + "/blob/main/LICENSE", -``` - -Add these entries so the theme can display the project name and author without duplicating them: - -```{code-block} python -:caption: html_context in conf\.py - -"project": project, -"author": author, -``` - -Add these entries to configure the settings related to your GitHub repository. -`default_edit_url` and `default_view_url` serve as fallback URLs for the view/edit source buttons on pages that do not have a specific source file path set. - -```{code-block} python -:caption: html_context in conf\.py - -"feedback": True, -"github_issues": "enabled", -"default_source_extension": default_source_extension, -"default_edit_url": github_repo + "/edit/main/docs/index" + default_source_extension, -"default_view_url": github_repo + "/blob/main/docs/index" + default_source_extension, -``` - -Add the horizontal navigation menu configuration: - -```{code-block} python -:caption: html_context in conf\.py - -# Horizontal Nav Menu -"company": "Canonical", -# "link1_URL": "https://example.com/", -# "link1_name": "First optional link", -# "link2_URL": "https://example.com/", -# "link2_name": "Second optional link", -``` - -Uncomment and adjust the parameters for `link1` and `link2` if you want to add the links in the top navigation bar. - -Add main logo parameters and adjust their values for your documentation: - -```{code-block} python -:caption: html_context in conf\.py - -# Canonical Product menu -# Uncomment if you need a product menu added on the top of every page -# "add_product_menu": True, - -"logo_link_URL": "https://documentation.ubuntu.com", -"logo_img_URL": "https://assets.ubuntu.com/v1/82818827-CoF_white.svg", -"logo_title": "Canonical", -``` - -Add the following parameters for the footer. - -```{code-block} python -:caption: html_context in conf\.py - -# TODO: Customize the footer. -"footer": { - # Whether to add the product name as the first entry. - "product": True, - # Whether to add the license as the second entry. - "license": True, - # List your footer entries. Accepts HTML tags. - "entries": [ - 'Manage your tracker settings', - ] -} -``` - -### Add syntax highlighting - -Add these syntax highlighting settings after the list of extensions: - -```{code-block} python -:caption: conf\.py - -highlight_language = "none" # default -pygments_style = "autumn" # see https://pygments.org/styles for more -``` - -### Configure the sitemap - -Add the lastmod setting to the sitemap section: - -```{code-block} python -:caption: conf\.py - -sitemap_show_lastmod = True -``` - -### Configure PDF output - -If you need to render your docs to PDF, add the following at the end of the configuration: - -```{code-block} python -:caption: conf\.py - -set_modern_pdf_config = True -``` - -### Update the copyright - -The Ulwazi theme expects a plain year string rather than the older {spellexception}`CC-BY-SA` format. - -```{code-block} python -:caption: conf\.py - -copyright = f"{datetime.date.today().year}" -``` - -The license information is now conveyed through the "license" key in "html_context". - -## Test the documentation - -Once configuration is complete, review everything again and build it from scratch (cleaning out the existing build files first): - -```shell -cd docs -make clean -make run -``` - -This will start a local server at http://127.0.0.1:8000. Open it in your browser to verify the pages render correctly. - -Report issues or feature requests in the [Ulwazi GitHub repository](https://github.com/canonical/ulwazi/issues/new). diff --git a/docs/explanation/assets/extensions.png b/docs/explanation/assets/extensions.png deleted file mode 100644 index 182275c7e64959323db3fcba05af8c81713780d8..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 60993 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 diff --git a/docs/explanation/assets/rtd-build.png b/docs/explanation/assets/rtd-build.png deleted file mode 100644 index e423a6baacd0d1543f5ff5e52b364d8567d84f4c..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 24574 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 diff --git a/docs/explanation/assets/sphinx.png b/docs/explanation/assets/sphinx.png deleted file mode 100644 index 710fbe59d30b398744a0231ef4d60499434b356e..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 17713 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 RcRJo=)IdCdSHi5r{|~VnA6x(c diff --git a/docs/explanation/build.rst b/docs/explanation/build.rst deleted file mode 100644 index a396fb4a..00000000 --- a/docs/explanation/build.rst +++ /dev/null @@ -1,78 +0,0 @@ -.. meta:: - :description: Learn about the function, structure, and design of the build process in Canonical's Starter Pack. - -:relatedlinks: [GNU Make](https://www.gnu.org/software/make/) - - -.. _build: - -Build -====== - -Canonical's Starter Pack uses Make as its build system. Make was chosen because it's -well-tested and available on all platforms. The majority of the build configuration is -defined in ``docs/Makefile``. - -Make is also the user interface for operating a project's docs. Authors and developers -call all docs actions with ``make ``. - -The docs build depends on environment variables like ``BUILDDIR`` to locate critical -files. They are conditional variables, so other systems can invoke the build at -different locations without changing the docs ``Makefile``. - -Being primarily a Python project, all dependencies are stored in a virtual environment, -``docs/.venv`` by default. The environment is ephemeral and subject to frequent change. -Installing the starter pack initializes it, while cleaning and upgrading tears it -down and rebuilds it. - - -.. _explanation-parent-project-build: - -Parent projects and the build ------------------------------ - -The starter pack is arranged as a standalone project. When it's used in a larger -project, the docs are a subsystem among other components. - -If the parent project uses a build system, Make or otherwise, the doc build exists in -parallel with the parent build. When embedded, the virtual environment and build recipe -files would be arranged along these lines: - -.. code-block:: - - Project - │ - ├── ... - ├── docs - │ ├── ... - │ ├── .venv - │ └── Makefile - ├── src - │ └── ... - ├── - └── - -With embedded docs, the parent build doesn't mesh with the docs build, which can cause -difficulty: - -- Contributors typically call the build commands from the root of the project. Some will - find it inconvenient to run the docs commands by switching to the ``docs`` directory - or manually calling the docs Makefile with ``make -C docs ``. -- Storing multiple virtual environments bloats the host system. It's reasonable for - project maintainers to prefer a shared build environment. -- The starter pack's upgrade process can make changes to many files in the ``docs`` - directory. Upgrading is potentially much simpler if the parent project modifies only - a minimum of files in the directory. -- With quality assurance and continuous integration, it's simpler if the project can use - the same interface to run local and remote checks. More specifically, the parent build - system and CI need a way to call the starter pack's ``links``, ``spelling``, and - ``vale`` checks. - -One possible resolution is for the parent build to manually recreate the docs build, -tightly coupling the parent build to the existing docs configuration. But this poses -another challenge, because the docs ``Makefile`` might change during a starter pack -update, requiring a rewrite of the parent build recipes. - -The solution to these complications is to create a bridge between the two builds, from -the parent build to the docs ``Makefile``. -:ref:`bridge-project-and-docs-builds` is a guide for how to do this. diff --git a/docs/explanation/components.rst b/docs/explanation/components.rst deleted file mode 100644 index c376191a..00000000 --- a/docs/explanation/components.rst +++ /dev/null @@ -1,137 +0,0 @@ -.. meta:: - :description: A breakdown of Canonical's Sphinx Starter Pack that covers its constituent elements and their purpose. - -.. _explanation-structure: - -Starter pack structure -======================= - -The Starter Pack is a template `Sphinx `__ -project. It provides a default file structure, a theme, and dependencies for Canonical -documentation. - - -Sphinx ------- - -Sphinx is a documentation static site generator that converts reStructuredText or -Markdown files into HTML. It's the core software in the Starter Pack. - -``docs/conf.py`` is a configuration file that defines the properties of the Sphinx -project such as project metadata and extensions. - -.. figure:: assets/sphinx.png - :class: with-border - - Sphinx as a documentation static site generator - - -Python ------- - -Because Sphinx is a Python application, the Starter Pack depends on Python and a Python -package manager. Most of its dependencies are Python packages. Local builds of the -Starter Pack require a Python virtual environment to isolate the project from the host -system. - -To be able to work on a Starter Pack project, your host needs Python 3.11, pip, and venv. - -.. figure:: assets/python-starter-pack.png - :class: with-border - - Python's role in the Starter Pack - - -Sphinx extensions ------------------ - -The syntax and behavior of Sphinx can be modified with extensions. These can be used to -create diagrams, test code, and more. - -The Starter Pack includes a curated and tested set of extensions. - -.. figure:: assets/extensions.png - :class: with-border - - Extension types - - -Built-in extensions -~~~~~~~~~~~~~~~~~~~ - -Built-in extensions do not need to be installed separately from Sphinx and can be -enabled through the configuration file. The ``conf.py`` file has already been -configured to enabled typical extensions necessary for documentation work. - - -Third-party extensions -~~~~~~~~~~~~~~~~~~~~~~ - -If an extension is not built into Sphinx, you must include it in the -``requirements.txt`` file before enabling it in the Sphinx configuration file. - -Extensions are Python packages, and the Starter Pack manages them with a -`requirements.txt `__ -file. - -.. figure:: assets/third-party.png - :class: with-border - - Third-party extensions - - -Markdown support -^^^^^^^^^^^^^^^^ - -By default, Sphinx uses reStructuredText. Markdown is supported through the `MyST parser -`_, which is enabled with the -``myst-parser`` extension. - - -Canonical theme -^^^^^^^^^^^^^^^ - -The Canonical theme is packaged as a standalone `canonical-sphinx -`_) extension. It is based on `Furo -`__ and is designed to follow Canonical branding. - - -Command-line tools ------------------- - -The Starter Pack uses Make as its local build system. The Starter Pack's Makefile -provides a command-line interface for setting up the virtual environment, installing -dependencies, building the documentation, and more. - - -Makefile -~~~~~~~~ - -Some of the Makefile targets (such as ``html`` and ``linkcheck``) provide Sphinx-native -functionality for building documentation or performing tests in a simplified form while -managing required dependencies. For example, instead of using the ``sphinx-build -linkcheck SOURCEDIR OUTPUTDIR`` command, you can use ``make linkcheck``. - -See :ref:`build` to learn how the local build process works. - -Additionally, the Makefile provides commands to trigger third-party CLI tools, such as -the Vale prose linter for :ref:`automatic-checks-styleguide`. - - -Read The Docs configuration file --------------------------------- - -Read The Docs is a documentation building and hosting platform. It takes the -documentation created using Sphinx (or other tools) and builds and publishes it online. - -If you are publishing your documentation through Read the Docs, the Read the Docs build -logic is declared in ``.readthedocs.yaml``. The Starter Pack comes with a pre-configured -``.readthedocs.yaml`` with default values that should work for the majority of projects. - -See :ref:`publish-on-rtd` to learn how configure your Read the Docs instance. - -.. figure:: assets/rtd-build.png - :class: with-border - - Read the Docs build configuration - diff --git a/docs/explanation/index.rst b/docs/explanation/index.rst index 34babe7a..f8ded01b 100644 --- a/docs/explanation/index.rst +++ b/docs/explanation/index.rst @@ -1,20 +1,4 @@ -.. meta:: - :description: Explore topics about the concepts and ideas in Canonical's Starter Pack. - - .. _explanation: Explanation =========== - -Explore topics about the concepts and ideas in Canonical's Starter Pack. - -The starter pack is built using standard Python tools, and is both deep and flexible. - -.. toctree:: - :maxdepth: 1 - - components - build - sitemaps - diff --git a/docs/explanation/sitemaps.rst b/docs/explanation/sitemaps.rst deleted file mode 100644 index 2dc6f44f..00000000 --- a/docs/explanation/sitemaps.rst +++ /dev/null @@ -1,187 +0,0 @@ -.. _sitemaps: - -Sitemaps -========= - -The latest version of the starter pack generates a sitemap for your documentation -using the `sphinx-sitemap `_ -extension. - -This page goes over the nuances of configuring sitemaps, as well as how the -extension must be configured in your starter pack project. - -Read the Docs-generated sitemaps ---------------------------------- - -RTD generates a basic sitemap pointing to the index page, and relies on -crawlers to index the site. This is sufficient for some projects, but RTD -does not generate sitemaps for subprojects. - -This means any project under the Ubuntu documentation library project must -generate its own sitemap. - -``sphinx-sitemap``-generated sitemaps --------------------------------------- - -The standard Starter Pack uses the ``dirhtml`` builder for Sphinx recipes in the -project's Makefile. - -If your project uses an older version of the Starter Pack or -changes the builder, the links generated by the sitemap will be malformed. Either -:ref:`update to the latest version of the Starter Pack ` or -ensure your project's recipes use the ``dirhtml`` builder, not ``html``. - -Ensure ``sphinx-sitemap`` has been added to your ``docs/requirements.txt`` file. - -Add ``sphinx_sitemap`` to ``extensions`` in your configuration file (:file:`docs/conf.py`): - -.. code-block:: - - extensions = ['sphinx_sitemap'] - -Sitemap configuration -^^^^^^^^^^^^^^^^^^^^^ - -The Sphinx starter pack's configuration file (:file:`docs/conf.py`) includes default sitemap configuration. - -The ``sphinx-sitemap`` extension requires a ``html_baseurl`` variable to be configured. - -This is set by default as follows: - -.. code-block:: python - - html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "/") - -When building on Read the Docs, this sets ``html_baseurl`` dynamically to the value of the -``READTHEDOCS_CANONICAL_URL`` environment variable, which resolves to the full URL of the documentation -including the version and language (if applicable). - -In local builds and builds on other hosts, ``html_baseurl`` defaults to ``/``. - -The ``sitemap_url_scheme`` variable is set to ``'{link}'`` by default. This uses the value of ``html_baseurl`` to generate -the full URL for each page for the sitemap. - -.. note:: - - If you are implementing a sitemap on an RTD instance that is not a subproject, - and it uses ``{link}`` for the ``sitemap_url_scheme``, RTD will replace your - sitemap with their own. - - This is a known bug. The only current workaround is to use a different - `sitemap name `_ - and a custom ``robots.txt`` pointing to it. - -``lastmod`` configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -As of version 2.7.0, the sitemap extension supports adding a ``lastmod`` date. -Make sure that your configuration file has:: - - sitemap_show_lastmod = True - -Exclude pages -------------- - -Pages can be excluded from the sitemap by adding them to `sitemap_excludes` in :file:`docs/conf.py`:: - - sitemap_excludes = [ - '404/', - 'genindex/', - 'search/', - ] - -Wildcards are supported. For example, ``_modules/*`` excludes the path ``_modules/`` and all paths such as ``_modules/foo/bar/``. For details, see `Excluding Pages `_. - -Validate your sitemap ---------------------- - -A sitemap will be available at different locations, depending on how it is -generated. - -Read the Docs generated sitemaps are available at the base domain of a project, -while sitemaps generated with this extension will be placed in the base of the URL -schema used. - -For example, two sitemaps are generated for the Sphinx sitemap's documentation -as it is hosted on RTD: - -* The first is generated by RTD and is available at the root of the domain: https://sphinx-sitemap.readthedocs.io/sitemap.xml -* The second is generated by the `sphinx-sitemap` extension and is available at the base of the URL schema used by the RTD instance: https://sphinx-sitemap.readthedocs.io/en/latest/sitemap.xml - -.. dropdown:: How to specify a sitemap - - A `robots.txt` file dictates which sitemap is used to index a website. You - can use a custom `robots.txt` file by creating your own and adding it to - `html_static_path` in your configuration file. An example can be found in the - `Ubuntu documentation library `_ - project. - -Support multiple versions -------------------------- - -The sphinx-sitemap extension doesn't support multiple versions by default. Configuring -your versioned documentation to use an appropriate version may be sufficient, as search -engines and other web systems crawl websites for the purposes of indexing. - -If you want sitemaps for all your documentation's versions, you need to deploy your own -``robots.txt`` file and sitemap index. Supporting multiple versions is recommended for -documentation with LTS releases, as it makes past versions more prominent to search -engines. - -For this task, we'll use the Starter Pack as an example. Let's assume it has three -versions, 1.0, 2.0, and 3.0, and uses the URL schema of ``/``. - -First, ensure each version of your documentation has a sitemap generated by this -extension with the appropriate version. - -Next, create a ``sitemapindex.xml`` file in the same directory as the configuration -file, and point to the sitemap files of each of your documentation sets: - -.. code-block:: xml - :caption: sitemapindex.xml - - - - https://canonical-starter-pack.readthedocs-hosted.com/stable/sitemap.xml - - - https://canonical-starter-pack.readthedocs-hosted.com/3.0/sitemap.xml - - - https://canonical-starter-pack.readthedocs-hosted.com/2.0/sitemap.xml - - - https://canonical-starter-pack.readthedocs-hosted.com/1.0/sitemap.xml - - - -Create a ``robots.txt`` file in the same directory as the configuration file. - -If necessary, block any paths you don't want crawled. Google describes how to do this in -`How to write and submit a robots.txt file -`__. - -At the end of ``robots.txt``, point to the future path of ``sitemapindex.xml``: - -.. code-block:: - :caption: robots.txt - - Sitemap: https://canonical-starter-pack.readthedocs-hosted.com/stable/sitemapindex.xml - -Lastly, add both new files to the configuration file: - -.. code-block:: - :caption: conf.py - - html_extra_path = [ - "sitemapindex.xml", - "robots.txt", - ] - -This provides a ``sitemapindex.xml`` file which points to the ``sphinx-sitemap`` -generated sitemap for each version. - -You may want to automate the generation of the ``sitemapindex.xml`` file. To see how -this is done for the Ubuntu documentation library project, which generates a sitemap -containing subproject sitemaps, see `the script here -`_. diff --git a/docs/how-to/assets/openapi._rst b/docs/how-to/assets/openapi._rst deleted file mode 100644 index 396913a9..00000000 --- a/docs/how-to/assets/openapi._rst +++ /dev/null @@ -1,22 +0,0 @@ -.. raw:: html - - -
- - - \ No newline at end of file diff --git a/docs/how-to/assets/openapi.yaml b/docs/how-to/assets/openapi.yaml deleted file mode 100644 index 4e53d08c..00000000 --- a/docs/how-to/assets/openapi.yaml +++ /dev/null @@ -1,24 +0,0 @@ -openapi: 3.0.3 -info: - title: Hello API - version: 1.0.0 -paths: - /hello: - get: - summary: Say hello - parameters: - - in: query - name: name - schema: - type: string - responses: - "200": - description: OK - content: - application/json: - schema: - type: object - properties: - message: - type: string - example: "Hello, world!" diff --git a/docs/how-to/assets/troubleshoot-stable-zombie-version.png b/docs/how-to/assets/troubleshoot-stable-zombie-version.png deleted file mode 100644 index 624aac1a97e0dd197dfa93a4495f509dfec8b705..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 70434 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, pass the variable explicitly to the sub-Make call to ensure it reaches the docs Makefile:: - - $(MAKE) -C docs run SPHINX_AUTOBUILD_OPTS="$(SPHINX_AUTOBUILD_OPTS)" - -This approach allows command-line overrides to work intuitively from the parent context. - -.. important:: - The :command:`run` target is very convenient while working on documentation updates. - - However, it is quite error-prone because it displays warnings or errors only when they occur. - If you save other files later, you might miss these messages. - - Therefore, you should always :ref:`build-clean` before finalising your changes. - -Build a PDF ------------ - -Build a PDF locally with the following command: - -.. code-block:: none - - make pdf - -PDF generation requires specific software packages. If these files are not found, a prompt will be presented and the generation will stop. - -Required software packages include: - -* dvipng -* fonts-freefont-otf -* latexmk -* plantuml -* tex-gyre -* texlive-font-utils -* texlive-fonts-recommended -* texlive-lang-cjk -* texlive-latex-extra -* texlive-latex-recommended -* texlive-xetex -* xindy - -On Linux, required packages can be installed with: - -.. code-block:: none - - make pdf-prep-force - -.. note:: - - When generating a PDF, the index page is considered a 'foreword' and will not be labelled with a chapter. - -.. important:: - - When generating a PDF, it is important to not use additional headings before a ``toctree``. Documents referenced by the - ``toctree`` will be nested under any provided headings. - - A ``rubric`` directive can be combined with the ``h2`` class to provide a heading-styled rubric in the HTML output. See the default ``index.rst`` for an example. - Rubric-based headings aren't included as entries in the table of contents or the navigation sidebar. diff --git a/docs/how-to/configure-your-project.rst b/docs/how-to/configure-your-project.rst deleted file mode 100644 index 94292f82..00000000 --- a/docs/how-to/configure-your-project.rst +++ /dev/null @@ -1,179 +0,0 @@ -.. meta:: - :description: How to configure project-specific parameters. - -.. _configure-your-project: - -Configure your project -====================== - -While the Starter Pack provides default configuration values for most settings, you'll need to set project-specific parameters like the project name to ensure the documentation reflects your project accurately. - -.. important:: - - After setting up your repository with the Starter Pack, you should track the changes made to the Starter Pack. - - Changes to the look and feel, as well as common functionality, will be automatically available through updates to the `Canonical Sphinx`_ extension. - - Changes to files that are part of the Starter Pack, for example, :ref:`automatic-checks`, might require you to manually update your repository with the required files. - See the Starter Pack's `change log`_ for the most relevant (and of course all breaking) changes. - -Configuration for a Starter Pack based documentation is set in the :file:`docs/conf.py` Sphinx configuration file. - -The Starter Pack's default configuration is prepared in a way that makes sense for most projects. -However, you must set some critical parameters that are unique for your project, like the project's name. - -In addition, you can find some optional parameters or add your own configuration parameters to the file. - -Required customisation ----------------------- - -You must check and update some of the parameters specific to your project. -Mandatory parameters are commented with the `TODO` keyword. - -The following are some highlights of the available configuration parameters. - -Update the project information -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Edit the :file:`docs/conf.py` file and update the configuration in the ``Project information`` section. -See the comments in the file for more information about each setting. - -Open Graph configuration -^^^^^^^^^^^^^^^^^^^^^^^^ - -When you post a link to your documentation somewhere (for example, on Mattermost or Discourse), it might be shown with a preview. -This preview is configured through the Open Graph Protocol (:spellexception:`OGP`) configuration. - -If you don't know yet where your documentation will be hosted, you can leave the URL empty. -If you do, specify the hosting URL. -You can leave the defaults for the website name and the preview image or specify your own. - -Optional customisation ----------------------- - -The Starter Pack contains several features that you can configure, or turn off if they aren't suitable for your documentation. - -Modify the template -~~~~~~~~~~~~~~~~~~~ - -The default Starter Pack templates provide an initial configuration for your documentation set, including: - -- Header template - The top section of the page that contains your product's tag image and name, a link to your product's page (if available), and a drop-down menu for "More resources". -- Footer template - The bottom section of the page that contains sequential navigation controls, copyright information, licensing details, and other relevant links. - -These project settings are configured in :file:`docs/conf.py` and are generally sufficient for most cases. -However, if you have additional requirements -- such as adding links to announcements or videos that are not part of the documentation -- you can override the default templates to customize them as needed. - -See the :ref:`custom-html-templates` guide for details on how to do so. - -Deactivate the feedback button -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -By default, the Starter Pack includes a feedback button at the top of each page. -This button redirects users to your GitHub issues page, and populates an issue for them with details of the page they were on when they clicked the button. - -If your project does not use GitHub issues, set the ``github_issues`` variable in the :file:`docs/conf.py` file to an empty value to disable both the feedback button and the issue link in the footer. - -If you want to deactivate the feedback button, but keep the link in the footer, set ``disable_feedback_button`` in the :file:`docs/conf.py` file to ``True``. - -Configure the contributor display -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -By default, the Starter Pack will display a list of contributors at the bottom of each page. -This requires the GitHub URL and folder to be configured. - -If you want to turn this contributor listing off, you can do so by setting the ``display_contributors`` variable in the :file:`docs/conf.py` file to ``False``. - -To configure that only recent contributors are displayed, you can set the ``display_contributors_since`` variable. -It takes any Linux date format (for example, a full date, or an expression like "3 months"). - -Add redirects -~~~~~~~~~~~~~ - -If you rename a source file, its URL will change. To prevent broken links, you should -add a redirect from the old URL to the new URL in this case. - -You can add redirects in the ``docs/redirects.txt`` file. The paths for internal -redirects are relative to the root of the docs project. - -.. code-block:: - - "path/to/old/page" "path/to/new/page" - -Destination paths can also be external URLs. - -.. code-block:: - - "path/to/old/page" "https://example.com/new-page" - -Configure included extensions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The Starter Pack includes a set of extensions that are useful for all documentation sets. -Some extensions are :ref:`enabled by default ` within the Starter Pack, but you can customize the selection in the :file:`docs/conf.py` file. - -The ``canonical_sphinx`` extension is required for the Starter Pack and provides the Furo-based theme and custom templates. - -To add new extensions needed for your documentation set, add them to the ``extensions`` parameter in :file:`docs/conf.py`. - -.. note:: - - If any additional extensions need specific Python packages, ensure they are installed alongside the other requirements by adding them to the :file:`docs/requirements.txt` file. - -Add page-specific configuration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can override some global configuration for specific pages. - -For example, you can configure whether to display Previous/Next buttons at the bottom of pages by setting the ``sequential_nav`` variable in the :file:`docs/conf.py` file. - -.. code:: python - - html_context = { - ... - "sequential_nav": "both" - } - -You can then override this default setting for a specific page (for example, to turn off the Previous/Next buttons by default, but display them in a multi-page tutorial). - -To do so, add `file-wide metadata`_ at the top of a page. -See the following examples for how to enable Previous/Next buttons for one page: - -|RST|:: - - :sequential_nav: both - - [Page contents] - -MyST:: - - --- - sequential_nav: both - --- - - [Page contents] - -Possible values for the ``sequential_nav`` field are ``none``, ``prev``, ``next``, and ``both``. -See the :file:`docs/conf.py` file for more information. - -Another example for page-specific configuration is the ``hide-toc`` field (provided by `Furo `_), which can be used to hide the page-internal table of content. -See `Hiding Contents sidebar`_. - -Add your own configuration --------------------------- - -Custom configuration parameters for your project can be used to extend or override the common configuration, or to define additional configuration that is not covered by the common ``conf.py`` file. - -The following links can help you with additional configuration: - -- `Sphinx configuration`_ -- `Sphinx extensions`_ -- `Furo documentation`_ (Furo is the Sphinx theme we use as our base) - -If you need additional Python packages for any custom processing you do in your documentation, add them to the :file:`docs/requirements.txt` file. - -Disable failure on warning --------------------------- - -The docs build (``make html``) is, by default, set to fail when a warning (``WARNING`` in the build log) is encountered. To disable this setting, remove the ``--failure-on-warning`` option from the command specified in the ``html`` target in the ``Makefile``. - diff --git a/docs/how-to/contributing-myst.md b/docs/how-to/contributing-myst.md deleted file mode 100644 index f8707224..00000000 --- a/docs/how-to/contributing-myst.md +++ /dev/null @@ -1,228 +0,0 @@ ---- -orphan: true ---- - - - - -# How to contribute - -We believe that everyone has something valuable to contribute, whether you're a coder, a writer, or a tester. Here's how and why you can get involved: - -- **Why join us?** Work with like-minded people, develop your skills, connect with diverse professionals, and make a difference. -- **What do you get?** Personal growth, recognition for your contributions, early access to new features, and the joy of seeing your work appreciated. -- **Start early, start easy**: Dive into code contributions, improve documentation, or be among the first testers. Your presence matters, regardless of experience or the size of your contribution. - -The guidelines below will help keep your contributions effective and meaningful. - -## Code of conduct - -When contributing, you must abide by the [Ubuntu Code of Conduct](https://ubuntu.com/community/docs/ethos/code-of-conduct). - -## Licence and copyright - - - -By default, all contributions to ACME are made under the AGPLv3 licence. See the [licence](https://github.com/canonical/ACME/blob/main/COPYING) in the ACME GitHub repository for details. - -All contributors must sign the [Canonical contributor licence agreement](https://canonical.com/legal/contributors), which grants Canonical permission to use the contributions. The author of a change remains the copyright owner of their code (no copyright assignment occurs). - -## Releases and versions - - - -ACME uses [semantic versioning](https://semver.org/); major releases occur once or twice a year. - -The release notes can be found [TODO: here](https://example.com). - -## Environment setup - - - -To work on the project, you need the following prerequisites: - -- [TODO: Prerequisite 1](http://example.com) -- [TODO: Prerequisite 2](http://example.com) - -To install and configure these tools: - -```bash -TODO: prerequisite command 1 -TODO: prerequisite command 2 -``` - -## Submissions - - - -If you want to address an issue or a bug in ACME, notify in advance the people involved to avoid confusion; also, reference the issue or bug number when you submit the changes. - -- Fork [our GitHub repository](https://github.com/canonical/ACME) and add the changes to your fork, properly structuring your commits, providing detailed commit messages, and signing your commits. - -- Make sure the updated project builds and runs without warnings or errors; this includes linting, documentation, code, and tests. - -- Submit the changes as a [pull request (PR)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork). - -Your changes will be reviewed in due time; if approved, they will eventually be merged. - -### Describing pull requests - - - -To be properly considered, reviewed, and merged, your pull request must provide the following details: - -- **Title**: Summarise the change in a short, descriptive title. -- **Description**: Explain the problem that your pull request solves. Mention any new features, bug fixes, or refactoring. -- **Relevant issues**: Reference any [related issues, pull requests, and repositories](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls). -- **Testing**: Explain whether new or updated tests are included. -- **Reversibility**: If you propose decisions that may be costly to reverse, list the reasons and suggest steps to reverse the changes if necessary. - -### Commit structure and messages - - - -Use separate commits for each logical change, and for changes to different components. Prefix your commit messages with the names of components they affect, using the code tree structure. For example, start a commit that updates the ACME service with `ACME/service:`. - -Use [conventional commits](https://www.conventionalcommits.org/) to ensure consistency across the project: - -```none -Ensure correct permissions and ownership for the content mounts - -* Work around an ACME issue regarding empty dirs: https://github.com/canonical/ACME/issues/12345 - -* Ensure the source directory is owned by the user running a container. - -Links: -- ... -- ... -``` - -Such structure makes it easier to review contributions and simplifies porting fixes to other branches. - -### Signing commits - - - -To improve contribution tracking, we use the developer certificate of origin -([DCO 1.1](https://developercertificate.org/) and require signed commits (using -the `-S` or `---gpg-sign` option) for all changes that go into the ACME project. - -```{code-block} none -git commit -S -m "acme/component: updated life cycle diagram" -``` - -Signed commits will have a GPG, SSH, or S/MIME signature that is -cryptographically verifiable, and will be marked with a "Verified" or -"Partially verified" badge in GitHub. This verifies that you made the changes or -have the right to commit it as an open-source contribution. - -To set up locally signed commits and tags, see [GitHub Docs - About commit -signature verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification). - -````{tip} -You can configure your Git client to sign commits by default for any local -repository by running: - -```{code-block} none -git config --global commit.gpgsign true -``` - -Once you have configured this, you no longer need to add ``-S`` to your -commits explicitly. - -See [GitHub Docs - Signing commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits) for more information. -```` - -If you've made an unsigned commit and encounter the "Commits must have verified -signatures" error when pushing your changes to the remote: - -1. Amend the most recent commit by signing it without changing the commit -message, and push again: - - ```{code-block} none - git commit --amend --no-edit -n -S - git push - ``` - -1. If you still encounter the same error, confirm that your GitHub account has -been set up properly to sign commits as described in the [GitHub Docs - About -commit signature verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification). - ```{tip} - If you use SSH keys to sign your commits, make sure to add a "Signing Key" - type in your GitHub account. See - [GitHub Docs - Adding a new SSH key to your account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account) - for more information. - ``` - -## Code - -### Formatting and linting - - - -ACME relies on these formatting and linting tools: - -- [TODO: Tool 1](http://example.com) -- [TODO: Tool 2](http://example.com) - -To configure and run them: - -```bash -TODO: lint command 1 -TODO: lint command 2 -``` - -### Structure - -- **Check linked code elements**: Ensure coupled code elements, files, and directories are adjacent. For instance, store test data close to the corresponding test code. -- **Group variable declaration and initialisation**: Declare and initialise variables together to improve code organisation and readability. -- **Split large expressions**: Break down large expressions into smaller self-explanatory parts. Use multiple variables where appropriate to make the code more understandable and choose names that reflect their purpose. -- **Use blank lines for logical separation**: Insert a blank line between two logically separate sections of code to improve its structure and readability. -- **Avoid nested conditions**: Avoid nesting conditions to improve readability and maintainability. -- **Remove dead code and redundant comments**: Drop unused or obsolete code and comments to promote a cleaner code base and reduce confusion. -- **Normalise symmetries**: Treat identical operations consistently, using a uniform approach to improve consistency and readability. - -### Best practices - - - -## Tests - - - -All code contributions must include tests. - -To run the tests locally before submitting your changes: - -```bash -TODO: test command 1 -TODO: test command 2 -``` - -## Documentation - -ACME's documentation is stored in the `DOCDIR` directory of the repository. It is based on the [Canonical Starter Pack](https://canonical-starter-pack.readthedocs-hosted.com/stable/) and hosted on [Read the Docs](https://about.readthedocs.com/). - -For general guidance, refer to the [Starter Pack guide](https://canonical-starter-pack.readthedocs-hosted.com/stable/). - -For syntax help and guidelines, refer to the syntax guides contained in the [rST](project:#rst-syntax) and [MyST](project:#myst-syntax) syntax guides. - -In structuring, the documentation employs the [Diátaxis](https://diataxis.fr/) approach. - -To run the documentation locally before submitting your changes: - -```bash -make run -``` - -### Automatic checks - -GitHub runs automatic checks on the documentation to verify spelling, validate links, and suggest inclusive language. - -You can (and should) run the same checks locally: - -```bash -make spelling -make linkcheck -make woke -``` diff --git a/docs/how-to/contributing.rst b/docs/how-to/contributing.rst deleted file mode 100644 index cc50b4e3..00000000 --- a/docs/how-to/contributing.rst +++ /dev/null @@ -1,330 +0,0 @@ -.. meta:: - :description: How to contribute to the documentation project with code, writing, or testing. - -:orphan: - -.. TODO: Replace all mentions of ACME with your project name -.. TODO: Update all sections containing TODOs; make sure no TODOs are left - - -How to contribute -================= - -We believe that everyone has something valuable to contribute, -whether you're a coder, a writer or a tester. -Here's how and why you can get involved: - -- **Why join us?** Work with like-minded people, develop your skills, - connect with diverse professionals, and make a difference. - -- **What do you get?** Personal growth, recognition for your contributions, - early access to new features and the joy of seeing your work appreciated. - -- **Start early, start easy**: Dive into code contributions, - improve documentation, or be among the first testers. - Your presence matters, - regardless of experience or the size of your contribution. - - -The guidelines below will help keep your contributions effective and meaningful. - - -Code of conduct ---------------- - -When contributing, you must abide by the -`Ubuntu Code of Conduct `_. - - -Licence and copyright ---------------------- - -.. TODO: Update with your license details or drop if excessive - -By default, all contributions to ACME are made under the AGPLv3 licence. -See the `licence `_ -in the ACME GitHub repository for details. - -All contributors must sign the `Canonical contributor licence agreement -`_, -which grants Canonical permission to use the contributions. -The author of a change remains the copyright owner of their code -(no copyright assignment occurs). - - -Releases and versions ---------------------- - -.. TODO: Add your release and versioning details or drop if excessive - -ACME uses `semantic versioning `_; -major releases occur once or twice a year. - -The release notes can be found `TODO: here `_. - - -Environment setup ------------------ - -.. TODO: Update with your prerequisites or drop if excessive - -To work on the project, you need the following prerequisites: - -- `TODO: Prerequisite 1 `_ -- `TODO: Prerequisite 2 `_ - - -To install and configure these tools: - -.. code-block:: console - - TODO: prerequisite command 1 - TODO: prerequisite command 2 - - -Submissions ------------ - -.. TODO: Suggest your own PR process or drop if excessive - -If you want to address an issue or a bug in ACME, -notify in advance the people involved to avoid confusion; -also, reference the issue or bug number when you submit the changes. - -- `Fork - `_ - our `GitHub repository `_ - and add the changes to your fork, - properly structuring your commits, - providing detailed commit messages - and signing your commits. - -- Make sure the updated project builds and runs without warnings or errors; - this includes linting, documentation, code and tests. - -- Submit the changes as a `pull request (PR) - `_. - - -Your changes will be reviewed in due time; -if approved, they will be eventually merged. - - -Describing pull requests -~~~~~~~~~~~~~~~~~~~~~~~~ - -.. TODO: Update with your own checklist or drop if excessive - -To be properly considered, reviewed and merged, -your pull request must provide the following details: - -- **Title**: Summarise the change in a short, descriptive title. - -- **Description**: Explain the problem that your pull request solves. - Mention any new features, bug fixes or refactoring. - -- **Relevant issues**: Reference any - `related issues, pull requests and repositories `_. - -- **Testing**: Explain whether new or updated tests are included. - -- **Reversibility**: If you propose decisions that may be costly to reverse, - list the reasons and suggest steps to reverse the changes if necessary. - - -Commit structure and messages -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. TODO: Update with your own guidelines or drop if excessive - -Use separate commits for each logical change, -and for changes to different components. -Prefix your commit messages with names of components they affect, -using the code tree structure, -e.g. start a commit that updates the ACME service with ``ACME/service:``. - -Use `conventional commits `_ -to ensure consistency across the project: - -.. code-block:: none - - Ensure correct permissions and ownership for the content mounts - - * Work around an ACME issue regarding empty dirs: - https://github.com/canonical/ACME/issues/12345 - - * Ensure the source directory is owned by the user running a container. - - Links: - - ... - - ... - - -Such structure makes it easier to review contributions -and simplifies porting fixes to other branches. - - -Signing commits -~~~~~~~~~~~~~~~ - -.. TODO: Update with your suggestions or drop if excessive - -To improve contribution tracking, we use the developer certificate of origin -(`DCO 1.1 `_) and require signed commits -(using the ``-S`` or ``--gpg-sign`` option) for all changes that go into the -ACME project. - -.. code-block:: none - - git commit -S -m "acme/component: updated life cycle diagram" - -Signed commits will have a GPG, SSH, or S/MIME signature that is -cryptographically verifiable, and will be marked with a "Verified" or -"Partially verified" badge in GitHub. This verifies that you made the changes or -have the right to commit it as an open-source contribution. - -To set up locally signed commits and tags, see `GitHub Docs - About commit -signature verification `_. - -.. tip:: - - You can configure your Git client to sign commits by default for any local - repository by running ``git config --global commit.gpgsign true``. - Once you have configured this, you no longer need to add ``-S`` to your - commits explicitly. - - See `GitHub Docs - Signing commits `_ for more information. - -If you've made an unsigned commit and encounter the "Commits must have verified -signatures" error when pushing your changes to the remote: - -1. Amend the most recent commit by signing it without changing the commit - message, and push again: - - .. code-block:: none - - git commit --amend --no-edit -n -S - git push -#. If you still encounter the same error, confirm that your GitHub account has - been set up properly to sign commits as described in the `GitHub Docs - About - commit signature verification `_. - - .. tip:: - - If you use SSH keys to sign your commits, make sure to add a "Signing Key" - type in your GitHub account. See - [GitHub Docs - Adding a new SSH key to your account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account) - for more information. - -Code ----- - -Formatting and linting -~~~~~~~~~~~~~~~~~~~~~~ - -.. TODO: Update with your linting configuration setup or drop if excessive - -ACME relies on these formatting and linting tools: - -- `TODO: Tool 1 `_ -- `TODO: Tool 2 `_ - - -To configure and run them: - -.. code-block:: console - - TODO: lint command 1 - TODO: lint command 2 - - -Structure -~~~~~~~~~ - -- **Check linked code elements**: - Check that coupled code elements, files and directories are adjacent. - For instance, store test data close to the corresponding test code. - -- **Group variable declaration and initialisation**: - Declare and initialise variables together - to improve code organisation and readability. - -- **Split large expressions**: - Break down large expressions - into smaller self-explanatory parts. - Use multiple variables where appropriate - to make the code more understandable - and choose names that reflect their purpose. - -- **Use blank lines for logical separation**: - Insert a blank line between two logically separate sections of code. - This improves its structure and makes it easier to understand. - -- **Avoid nested conditions**: - Avoid nesting conditions to improve readability and maintainability. - -- **Remove dead code and redundant comments**: - Drop unused or obsolete code and comments. - This promotes a cleaner code base and reduces confusion. - -- **Normalise symmetries**: - Treat identical operations consistently, using a uniform approach. - This also improves consistency and readability. - - -Best practices -~~~~~~~~~~~~~~ - -.. TODO: Update with your best practices or drop if excessive - - -Tests ------ - -.. TODO: Update with your testing framework details or drop if excessive - -All code contributions must include tests. - -To run the tests locally before submitting your changes: - -.. code-block:: console - - TODO: test command 1 - TODO: test command 2 - - -Documentation -------------- - -ACME's documentation is stored in the ``DOCDIR`` directory of the repository. -It is based on the `Canonical Starter Pack -`_ -and hosted on `Read the Docs `_. - -For syntax help and guidelines, -refer to the Canonical syntax guides -(:ref:`reStructuredText ` and :ref:`MyST `). - -In structuring, -the documentation employs the `Diátaxis `_ approach. - -To run the documentation locally before submitting your changes: - -.. code-block:: console - - make run - - -Automatic checks -~~~~~~~~~~~~~~~~ - -GitHub runs automatic checks on the documentation -to verify spelling, validate links and suggest inclusive language. - -You can (and should) run the same checks locally: - -.. code-block:: console - - make spelling - make linkcheck - make woke diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst index 481edfcc..d7a5b154 100644 --- a/docs/how-to/index.rst +++ b/docs/how-to/index.rst @@ -1,43 +1,4 @@ -.. meta:: - :description: Explore the essential guides and procedures in Canonical's Starter Pack. - - .. _how-to-guides: How-to guides ============= - -These guides will walk you through the processes involving setting up, -maintaining, and contributing to the Starter Pack. - -Basic setup and maintenance ---------------------------- - -Set up, configure, update, and customize your project to keep it organized and aligned with -your documentation needs. - -.. toctree:: - :maxdepth: 1 - - configure-your-project - build-and-preview - publish-on-rtd - update-starter-packs/index.rst - troubleshooting - -Optional features and customisation ------------------------------------ - -As your documentation grows, you may need more advanced features to support richer content. This -can include customising the build system, adding diagrams as code, rendering API references, interactive -tables, and custom HTML. - -While some of these features are available by default in the Starter Pack, others may require additional -extensions. - -The following guides will help you get started: - -.. toctree:: - :maxdepth: 2 - - optional-customisation/index.rst diff --git a/docs/how-to/optional-customisation/add-documentation-testing.rst b/docs/how-to/optional-customisation/add-documentation-testing.rst deleted file mode 100644 index d89b6511..00000000 --- a/docs/how-to/optional-customisation/add-documentation-testing.rst +++ /dev/null @@ -1,330 +0,0 @@ -.. meta:: - :description: How to use Spread to automatically test commands in documentation and keep them in sync with your product. - -.. _how-to-add-documentation-testing: - -Use Spread to test commands in documentation -============================================ - -It's challenging to keep documentation in sync with products as they evolve. This -process is aided by *Spread*, a test distributor that can work through your -documentation and report failures in GitHub workflows. - -By using Spread tests, you can rely on the tests as the source of truth for commands -in your documentation, enabling fully tested documentation at build time. - -What you'll need ----------------- - -* `Multipass `_ installed on your machine -* `Spread `_ installed on your machine - -.. warning:: - - Spread requires elevated permissions to run as root. Use the - `Go install method `_ - recommended in the Spread README to install Spread. - -Create a test suite -------------------- - -From the root of your project, create the file ``spread.yaml`` and insert the -following contents: - -.. code-block:: yaml - :caption: project_name/spread.yaml - - project: project_name - - path: /project_name - -Match the ``project`` name to your main directory's name. -The ``path`` designates the directory where the Spread -materials exist. - -So that Spread knows about your tests, add the -following section to the end of ``spread.yaml``: - -.. code-block:: yaml - :caption: project_name/spread.yaml - :emphasize-lines: 5-9 - - project: project_name - - path: /project_name - - suites: - tests/spread/: - summary: example test - systems: - - ubuntu-24.04-64 - -The ``suites`` section is how you tell Spread about the various Spread tests in -your project along with the systems you want Spread to use. -In this example, Spread looks for tests in the ``project_name/tests/spread`` directory and -runs them on Ubuntu 24.04. -If you create a new ``task.yaml`` file in a different directory, -remember to add a corresponding suite for it in ``spread.yaml``. - -Set up the Multipass backend ----------------------------- - -Each job in Spread has a backend, or a way to obtain a machine for running your Spread -tests. Spread can run on various backends, like -`Google `__, -`QEMU `__, or, as this -guide sets up, Multipass. - -Copy the following ``backends`` section of ``spread.yaml`` between the ``path`` and -``suites`` sections: - -.. code-block:: yaml - :caption: project_name/spread.yaml - :emphasize-lines: 5-40 - - project: project_name - - path: /project_name - - backends: - multipass: - type: adhoc - allocate: | - multipass_image=24.04 - instance_name="example-multipass-vm" - - # Launch Multipass VM - multipass launch --cpus 2 --disk 10G --memory 2G --name "${instance_name}" "${multipass_image}" - - # Enable PasswordAuthentication for root over SSH. - multipass exec "$instance_name" -- \ - sudo sh -c "echo root:${SPREAD_PASSWORD} | sudo chpasswd" - multipass exec "$instance_name" -- \ - sudo sh -c \ - "if [ -d /etc/ssh/sshd_config.d/ ] - then - echo 'PasswordAuthentication yes' > /etc/ssh/sshd_config.d/10-spread.conf - echo 'PermitRootLogin yes' >> /etc/ssh/sshd_config.d/10-spread.conf - else - sed -i /etc/ssh/sshd_config -E -e 's/^#?PasswordAuthentication.*/PasswordAuthentication yes/' -e 's/^#?PermitRootLogin.*/PermitRootLogin yes/' - fi" - multipass exec "$instance_name" -- \ - sudo systemctl restart ssh - - # Get the IP from the instance - ip=$(multipass info --format csv "$instance_name" | tail -1 | cut -d\, -f3) - ADDRESS "$ip" - - discard: | - instance_name="example-multipass-vm" - multipass delete --purge "${instance_name}" - - systems: - - ubuntu-24.04-64: - workers: 1 - - suites: - tests/spread/: - summary: example test - systems: - - ubuntu-24.04-64 - -The ``backends`` section contains the following pieces: - -* The backend is designated as ``type: adhoc`` as you must explicitly - script the procedure to allocate and discard the Multipass VM. -* The ``allocate`` section defines the image and name of the VM, launches the - VM, and sets up the proper SSH permissions Spread then logs in to the VM with - root permissions and inserts the Spread test. The last two lines tell Spread the - IP address of the Multipass VM and set the environment variable ``ADDRESS``. -* The ``discard`` section deletes the Multipass VM once the Spread test - has finished running. -* The ``systems`` key notes which systems the backend uses. Note that this key - must match the ``systems`` used by at least one test under ``suites``. - -Create a Spread task --------------------- - -Put your Spread files alongside your project's existing tests. -The rest of this guide assumes they're in a top-level -``tests/spread`` directory. - -Each Spread test requires a dedicated ``task.yaml`` file that contains -all the commands you want to test. A single ``task.yaml`` can help you -validate an entire assumed workflow, for instance, -an end-to-end tutorial. - -An example ``task.yaml`` file is shown below: - -.. code-block:: yaml - :caption: task.yaml - - summary: Example Spread test - - kill-timeout: 5m - - prepare: | - echo "Use this section to install any prerequisites" - - execute: | - echo "This is the first command that Spread will run" - - echo "This is the second command that Spread will run" - -The ``summary`` section contains a brief description of the documentation you're testing, -the ``prepare`` section contains any initial setup your test needs, -and the ``execute`` section contains your documentation's commands. -The ``kill-timeout`` option has a default of 10 minutes and doesn't need to be -included if you expect your test to complete in that time frame. - -.. note:: - - For a real-world example, see ``task.yaml`` for - `the Rockcraft Go tutorial. `_ - -Include the tested commands in documentation --------------------------------------------- - -By using the ``literalinclude`` directive in Sphinx, you can insert the -exact commands from ``task.yaml`` in your documentation file. - -For example, consider the following ``task.yaml`` file: - -.. code-block:: yaml - :caption: task.yaml - - summary: Clone and build the Starter Pack - - kill-timeout: 5m - - execute: | - # [docs:clone-starter-pack] - git clone https://github.com/canonical/sphinx-docs-starter-pack.git - # [docs:clone-starter-pack-end] - - # [docs:build-documentation] - cd sphinx-docs-starter-pack/docs - make run - # [docs:build-documentation-end] - -Include the commands from ``task.yaml`` in your documentation with: - -.. tab-set:: - - .. tab-item:: reStructuredText - :sync: rest-commands - - .. code-block:: rst - :caption: Example ``literalinclude`` blocks - - Clone the Starter Pack: - - .. literalinclude:: relative-path-to/task.yaml - :language: bash - :start-after: [docs:clone-starter-pack] - :end-before: [docs:clone-starter-pack-end] - :dedent: 2 - - Enter the ``docs`` folder and build the project: - - .. literalinclude:: relative-path-to/task.yaml - :language: bash - :start-after: [docs:build-documentation] - :end-before: [docs:build-documentation-end] - :dedent: 2 - - .. tab-item:: MyST - :sync: myst-commands - - .. code-block:: md - :caption: Example ``literalinclude`` blocks - - Clone the Starter Pack: - - ```{literalinclude} relative-path-to/task.yaml - :language: bash - :start-after: [docs:clone-starter-pack] - :end-before: [docs:clone-starter-pack-end] - :dedent: 2 - ``` - - Enter the `docs` folder and build the project: - - ```{literalinclude} relative-path-to/task.yaml - :language: bash - :start-after: [docs:build-documentation] - :end-before: [docs:build-documentation-end] - :dedent: 2 - ``` - -By using the options ``:start-after:`` and ``:end-before:``, the documentation file -sources and includes all commands appearing in ``task.yaml`` between the -specified lines. - -Run tests locally ------------------ - -List all available Spread tests in the code repository: - -.. code-block:: bash - - spread --list - -The terminal should respond with all the tests defined in ``spread.yaml``. -For example: - -.. terminal:: - :dir: project_name - - spread --list - - multipass:ubuntu-24.04-64:tests/spread/example_documentation_test - -Run all Spread tests locally with ``spread``. You can also run a single -Spread test by specifying: - -.. code-block:: bash - - spread -vv -debug multipass:ubuntu-24.04-64:tests/spread/example_documentation_test - -Depending on the complexity of your test, Spread can take several minutes to complete. -The ``-vv -debug`` flags provide useful debugging information as the test runs. - -Check the results ------------------ - -During runtime, the terminal outputs various messages about allocating the Multipass VM, -connecting to the VM, sending the Spread test to the VM and executing the test. -If the test is successful, the terminal will output something similar to the following: - -.. terminal:: - :output-only: - - 2025-02-04 16:17:10 Successful tasks: 1 - 2025-02-04 16:17:10 Aborted tasks: 0 - -Another sign of a successful test is whether the Multipass VM was deleted as expected. -Check by running :code:`multipass list`, and if the Spread test was successful -(and you have no other Multipass VMs created at the time), the terminal should -respond with: - -.. terminal:: - :dir: project_name - - multipass list - - No instances found. - -If the Spread test failed, then the ``-debug`` flag will open a shell into the -Multipass VM so that additional debugging can happen. In that case, the terminal -will output something similar to the following: - -.. terminal:: - :output-only: - - 2025-02-04 16:17:10 Starting shell to debug... - 2025-02-04 16:17:10 Sending script for multipass:ubuntu-24.04-64 (multipass:ubuntu-24.04-64:tests/spread/example_documentation_test): - - -.. _ReStructuredText (.rst): https://www.sphinx-doc.org/en/master/usage/restructuredtext -.. _MyST-Markdown: https://myst-parser.readthedocs.io/en/latest diff --git a/docs/how-to/optional-customisation/bridge-project-and-docs-builds.rst b/docs/how-to/optional-customisation/bridge-project-and-docs-builds.rst deleted file mode 100644 index 9228c4dc..00000000 --- a/docs/how-to/optional-customisation/bridge-project-and-docs-builds.rst +++ /dev/null @@ -1,353 +0,0 @@ -.. meta:: - :description: How to bridge the build of Canonical's Starter Pack and a parent project's build. - -:relatedlinks: [pip and dependency groups](https://pip.pypa.io/en/stable/user_guide/#dependency-groups), [uv and dependency groups](https://docs.astral.sh/uv/concepts/projects/dependencies/#dependency-groups), [Poetry and dependency groups](https://python-poetry.org/docs/managing-dependencies#dependency-groups) - - -.. _bridge-project-and-docs-builds: - -Bridge project and documentation builds -======================================= - -.. If more parent projects and build systems are tested, make the introduction general - and add tabs to each of the steps - -The Starter Pack can be used as a standalone docs repository, or embedded inside a -parent project. This guide demonstrates how to bridge the docs build with a Python -project's main build. Once bridged, project contributors can install, build, and check -the docs from the root of the project with the main build system. - -:ref:`explanation-parent-project-build` describes the full benefits of bridging the -build in a larger project. - - -.. _how-to-bridge-project-builds-project-requirements-layout: - -Plan and requirements ---------------------- - -The bridge is built by making up to three changes to the build. - -The bridge **shims the docs build targets in the main build**. Any build system is -capable of adding targets that call other systems. When shimmed, the docs targets like -``html`` and ``clean`` pass through to ``docs/Makefile``, with arguments. - -The bridge also **merges the virtual environments**, removing the need for a separate -docs environment. This change is optional but recommended. To combine environments, your -project must provide **Python 3.11** or higher to the Starter Pack. Any Python -dependency manager will do, and this guide illustrates with three: - -- pip 25.1 and higher -- uv 0.4.27 and higher -- Poetry 1.2.0a2 and higher - -After adding the bridge, it's also possible to **adjust the documentation workflows** to -use your project's main build. The workflows were designed with Make, so they only work -if you use it for your build system. - - -Example project layout ----------------------- - -This guide illustrates the bridge through an example project. In the example project, -the file tree contains: - -.. code-block:: - - Project - │ - ├── ... - ├── docs - │ └── Makefile - ├── .venv - ├── Makefile - └── pyproject.toml - -The example project's root ``Makefile`` has two conventional targets that need -adjustment: - -- ``setup`` for building the virtual environment and syncing dependencies -- ``clean`` for cleaning up the virtual environment and temporary files - - -.. _how-to-bridge-project-builds-set-docs-env-vars: - -Set the build paths -------------------- - -Where your main build sets environment variables, redeclare the docs environment -variables that specify the build paths: - -- ``BUILDDIR`` is the destination for the docs. If you have special distribution needs - you can override this, but for most builds this can be left as-is. -- ``VENVDIR`` is the virtual environment of the docs. If you're merging the virtual - environments, set this as a relative path from the docs directory to your project's - virtual environment. -- ``VALEDIR`` is the path to the Vale binary. The full path depends on the - location of your virtual environment, so it's best to copy this as-is. - -In the example project, this looks like: - -.. code-block:: make - :caption: Makefile - - # Env vars for the docs build - export BUILDDIR ?= _build - export VENVDIR ?= ../.venv - export VALEDIR ?= $(VENVDIR)/lib/python*/site-packages/vale - - -.. _how-to-bridge-project-builds-integrate-docs-setup: - -Integrate the docs setup ------------------------- - -The next step is to incorporate the docs installation target, and optionally the -dependencies, into the main build. - - -Separate virtual environments -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If you don't plan to merge the virtual environments, override the installation target by -calling all three doc installation targets in a row. - -In the example project, this is written as: - -.. code-block:: make - :caption: Makefile - - # Override the - .PHONY: docs-install - docs-install: - $(MAKE) -C docs install --no-print-directory - $(MAKE) -C docs vale-install --no-print-directory - $(MAKE) -C docs pymarkdownlnt-install --no-print-directory - - -Merged virtual environments -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To merge virtual environments, you make the main ``setup`` target handle both -development and docs packages, and enumerate all docs packages in ``pyproject.toml``. - -By adding dependency groups, the docs packages, plus any custom Sphinx extensions, can -be managed by the main build and stored in one virtual environment. The result will be -three dependency groups in ``pyproject.toml``: - -- ``dev`` for development builds -- ``docs`` for extra docs packages that your project needs -- ``docs-starter-pack`` for the core docs packages set by the Starter Pack - -First, add these dependency groups, and make the docs dependencies include the -Starter Pack packages: - -.. code-block:: toml - :caption: pyproject.toml - - [dependency-groups] - dev = [ - # Packages for main development and testing - ] - docs = [ - # Packages for extra docs features - {include-group = "docs-starter-pack"}, - ] - docs-starter-pack = [ - # Core docs packages - ] - -If you don't already have a ``dev`` dependency group, review the packages listed in the -file's ``dependencies`` key, then move any non-runtime dependencies to the ``dev`` -dependency group. - -If your project needs extra docs features, like the Mermaid or LaTeX Sphinx extensions, -add their packages to the ``docs`` group. - -Copy the contents of ``docs/requirements.txt`` into the ``docs-starter-pack`` group. - -In the main build, override the docs installation target and make the project's -``setup`` target depend on it. In the example project, it is written like this: - -.. tabs:: - - .. tab:: pip - - .. code-block:: make - :caption: Makefile - :emphasize-lines: 2-3, 7-12 - - .PHONY: setup - setup: docs-install - pip install --group dev - - # ... - - # Override for `install` target in docs project - .PHONY: docs-install - docs-install: - pip install --group docs - $(MAKE) -C docs vale-install --no-print-directory - $(MAKE) -C docs pymarkdownlnt-install --no-print-directory - - .. tab:: uv - - .. code-block:: make - :caption: Makefile - :emphasize-lines: 2-3, 7-12 - - .PHONY: setup - setup: docs-install - uv sync --group dev - - # ... - - # Override for `install` target in docs project - .PHONY: docs-install - docs-install: - uv sync --no-dev --group docs - $(MAKE) -C docs vale-install --no-print-directory - $(MAKE) -C docs pymarkdownlnt-install --no-print-directory - - .. tab:: Poetry - - .. code-block:: make - :caption: Makefile - :emphasize-lines: 2-3, 7-12 - - .PHONY: setup - setup: docs-install - poetry install --only dev - - # ... - - # Override for `install` target in docs project - .PHONY: docs-install - docs-install: - poetry install --only docs - $(MAKE) -C docs vale-install --no-print-directory - $(MAKE) -C docs pymarkdownlnt-install --no-print-directory - -If your docs aren't written in Markdown, remove the command that runs the -``pymarkdownlnt-install`` target. - - -.. _how-to-bridge-project-builds-shim-remaining-targets: - -Shim the remaining targets --------------------------- - -The docs build has many targets, but only a handful of them overlap or collide with most -project builds, so we only need to override two more. The rest can pass straight through -to the docs build. - -In the example project, the main build calls the targets like this: - -.. code-block:: make - :caption: Makefile - - # Override for `clean` target in docs project. We don't want to touch `.venv`, - # so we pass a temp dir instead. - .PHONY: docs-clean - docs-clean: - VENVDIR=$(mktemp) $(MAKE) -C docs clean --no-print-directory - - # Override for `help` target - .PHONY: docs-help - docs-help: - @echo "Commands in the documentation subproject:" - $(MAKE) -C docs help --no-print-directory - @echo "Run these commands with 'make docs-' in the project root." - - # Shim for the rest of the targets in docs Makefile - .PHONY: docs-% - docs-%: docs-install - $(MAKE) -C docs $(@:docs-%=%) --no-print-directory - -.. admonition:: Variables and Makefiles - - When calling another Makefile with ``$(MAKE) -C``, also known as a sub-Make call, variables with default values in the child Makefile won't be overridden. To override them, you must set them explicitly with `export` or as as command-line arguments. - - For example, within the main build, if you need to customize ``SPHINX_AUTOBUILD_OPTS``, pass it to the docs build like this: - - .. code-block:: make - :caption: Makefile - - $(MAKE) -C docs run SPHINX_AUTOBUILD_OPTS="$(SPHINX_AUTOBUILD_OPTS)" - -.. _how-to-bridge-project-builds-adjust-rtd-build: - -Adjust the Read the Docs build ------------------------------- - -With the Makefile in a different location than usual, and its being a separate process, -it's simplest to override the Read the Docs build in ``.readthedocs.yaml`` to call the -same build targets that developers use locally. - -If you use an uncommon system, you might need to install it during the workflow's -``create_environment`` job. - -If you merged the virtual environments, make sure to set ``VENVDIR=${READTHEDOCS_VIRTUALENV_PATH}`` in all commands. - -Here's what it looks like in the example project: - -.. code-block:: yaml - :caption: .readthedocs.yaml - :emphasize-lines: 8-14 - - build: - os: ubuntu-24.04 - tools: - python: "3.12" - jobs: - post_checkout: - - git fetch --tags --unshallow # Also fetch tags - create_environment: - - python3 -m venv "${READTHEDOCS_VIRTUALENV_PATH}" - install: - - make docs-install VENVDIR="${READTHEDOCS_VIRTUALENV_PATH}" - build: - html: - - make docs VENVDIR="${READTHEDOCS_VIRTUALENV_PATH}" BUILDDIR="$READTHEDOCS_OUTPUT/html/" - - -.. _how-to-bridge-project-builds-adjust-doc-workflows: - -Adjust the doc workflows ------------------------- - -If your project uses the Starter Pack's docs workflows *and* Make, adjust the workflows -to use the bridged targets. - -For the main checks, override the target names and paths through the `workflow inputs -`_: - -.. code-block:: yaml - :caption: .github/workflows/automatic-doc-checks.yml - :emphasize-lines: 5, 7-11 - - jobs: - documentation-checks: - uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main - with: - working-directory: "." - fetch-depth: 0 - install-target: docs-install - spelling-target: docs-spelling - woke-target: docs-woke - linkcheck-target: docs-linkcheck - pa11y-target: docs-pa11y - -If your docs are written in Markdown, override the path and command inputs in the -Markdown linter workflow: - -.. code-block:: yaml - :caption: .github/workflows/markdown-style-checks.yml - :emphasize-lines: 2-6 - - - name: Create venv - working-directory: "." - run: make docs-install - - name: Lint markdown - working-directory: "." - run: make docs-lint-md diff --git a/docs/how-to/optional-customisation/custom-html-templates.md b/docs/how-to/optional-customisation/custom-html-templates.md deleted file mode 100644 index ec7c8198..00000000 --- a/docs/how-to/optional-customisation/custom-html-templates.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -myst: - html_meta: - description: How to extend or override default HTML templates to customize documentation structure and layout. ---- - -(custom-html-templates)= - -# Use custom HTML templates - -If the default template in the Starter Pack doesn't fully meet your needs -- whether you want a unique layout, a custom header or footer, or a specialized sidebar for certain pages -- you can create and use a custom template for your project. - -This guide shows you how to extend or override the default templates in the Starter Pack to tailor the look and structure of your documentation. - -```{note} -Base template customizations can be made to your documentation. -However, they are not officially supported by the team maintaining the Starter Pack. -Use them at your own discretion. -``` - -## Setup - -First, create the {file}`docs/_templates` directory; all your custom templates will need to be stored in this folder. - -Then uncomment this line in {file}`docs/conf.py` so your project will use local templates (where available): - -```{code-block} py -:caption: conf\.py - -templates_path = ["_templates"] -``` - -In most cases, you will need to copy the default templates from the [canonical-sphinx theme] as a starting point and edit as needed. - - -```{seealso} -Sphinx uses the Jinja templating engine for its HTML templates; see the [Jinja template syntax reference] for more details. -``` - -## Use custom template for all pages - -Sphinx looks for a template called {file}`page.html` as the entry point and main page template for documentation pages. -To customize your project's look and structure, check this file and determine which parts -- such as the header, footer, or sidebars -- need to be edited or overridden. - -Here are some examples. - -### Remove on-page TOC - -To remove the on-page TOC in the right sidebar, make a copy of [page.html] in the {file}`docs/_templates` folder, and remove the applicable lines. -This will apply to all pages. - -```{code-block} html -:caption: page.html -:emphasize-lines: 3-14 -:class: no-copybutton - -{% block right_sidebar %} -
- {% if not furo_hide_toc_orig %} -
- - {{ _("Contents") }} - -
-
-
- {{ toc }} -
-
- {% endif %} - {% if meta and ((meta.discourse and discourse_prefix) or meta.relatedlinks) %} -
- -``` - -### Add icon for GitHub link in header - -To customize the default header by adding an icon for the GitHub link, first make a copy of [header.html] in the {file}`docs/_templates` folder. - -Then modify the conditional statement related to the GitHub URL with your code. - -```{code-block} html -:caption: header.html -:emphasize-lines: 5-13 - -[...] - {% if github_url %} -
  • - - - - - - GitHub - -
    • - {% endif %} -[...] -``` - -## Use custom template for specific pages - -If you want to use a custom template for specific pages in your project, you can do so by using conditional logic in {file}`page.html`. - -First, create the base template with your modifications (e.g. {file}`special-header.html`, {file}`special-page.html`) and place it in the {file}`docs/_templates` folder. - -Next, make a copy of [page.html]. - -### Partial template changes - -To make partial changes (e.g. custom header) to specific pages, modify only the relevant parts of {file}`page.html` where you want the custom layout or behavior to apply. -For example, wrap the body block in a conditional statement so the custom header (e.g. {file}`special-header.html`) applies only to the "how-to/custom-templates" and "how-to/build" page. - -```{code-block} html -:emphasize-lines: 2-6 -:caption: _templates/page.html - -{% block body -%} - {% if pagename in ["how-to/build", "how-to/custom-templates"] %} - {% include "special-header.html" %} - {% else %} - {% include "header.html" %} - {% endif %} - {{ super() }} -{%- endblock body %} -``` - -### Whole template changes - -To make changes to the whole template (e.g. a custom layout for a landing page or marketing page), modify the `extends` statement in {file}`page.html` to specify the pages that will use different templates. -For example, the {file}`special-page.html` template applies only to the "how-to/customise" and "how-to/diagrams-as-code" page. - -```{code-block} html -:caption: _templates/page.html - -{% if pagename in ["how-to/customise", "how-to/diagrams-as-code"] %} - {% extends "special-page.html" %} -{% else %} - {% extends "furo/page.html" %} -{% endif %} -``` - -```{note} -The pages "how-to/customise" and "how-to/diagrams-as-code" will use {file}`special-page.html` as the base template, but all other blocks (e.g. footer, body, etc) will follow the default {file}`page.html`. -``` - -% LINKS -[canonical-sphinx theme]: https://github.com/canonical/canonical-sphinx/tree/main/canonical_sphinx/theme/templates -[Jinja template syntax reference]: https://jinja.palletsprojects.com/en/latest/templates/ -[page.html]: https://github.com/canonical/canonical-sphinx/blob/main/canonical_sphinx/theme/templates/page.html -[header.html]: https://github.com/canonical/canonical-sphinx/blob/main/canonical_sphinx/theme/templates/header.html diff --git a/docs/how-to/optional-customisation/customise-pdf.rst b/docs/how-to/optional-customisation/customise-pdf.rst deleted file mode 100644 index ed90eb02..00000000 --- a/docs/how-to/optional-customisation/customise-pdf.rst +++ /dev/null @@ -1,270 +0,0 @@ -.. meta:: - :description: How to customize PDF output with LaTeX. - -.. _pdf-customise: - -Customise PDF output -==================== - -Overview --------- - -The Starter Pack supports PDF output via LaTeX using the ``make pdf`` command. This build process relies on system packages, Sphinx configurations, and a LaTeX template from the ``canonical-sphinx`` extension. - -Customising PDF output involves two levels of configuration: - -* **Sphinx configuration**: built-in options for configuring LaTeX build process in :file:`conf.py`, for example: the engine used to generate the PDF, output file name, and input file paths. -* **LaTeX configuration**: the LaTeX packages, styling, and configuration for the PDF output, set through the :literalref:`latex_elements ` dictionary in the project :file:`conf.py`. In the starter-pack, a default set of LaTeX elements is provided by the ``canonical-sphinx`` extension. Changing the LaTeX configuration requires overriding the default values loaded from the extension. - -This guide covers common practices and tips for customising PDF output from your project using the Starter Pack and the ``canonical-sphinx`` extension. - -For basic instructions about building the PDF, see :ref:`build-and-preview`. - -Configure document properties ------------------------------ - -The :literalref:`latex_documents ` variable in the Sphinx :file:`conf.py` file controls properties of the intermediate LaTeX file and the final PDF output. The values are defined in a tuple of six elements: - -.. code-block:: python - - latex_documents = [ - ( - 'startdocname', # Root document (e.g., 'index' or 'pdf-index') - 'targetname.tex', # Output LaTeX file name (no spaces) - 'title', # Document title (can be empty to use the root doc's title) - 'author', # Author name(s). - 'theme', # Document type: 'manual' or 'howto' - True, # toctree_only: if True, only include docs in toctree - ), - ] - -* ``startdocname``: The root document for the PDF (without the .rst extension). -* ``targetname``: The filename for the generated LaTeX source file. The PDF file name is derived from this filename with the ``.pdf`` extension. Blank space characters are not allowed. -* ``title``: The title for the PDF document on the cover page. -* ``author``: The author(s) of the document. Use ``\\and`` to separate multiple authors. -* ``theme``: Either ``manual`` or ``howto``. - - * ``manual``: This is the default and is intended for comprehensive, book-style documentation. It produces a PDF with chapters, sections, and a table of contents. Use this for user guides, reference manuals, or any documentation that should be structured as a book. - * ``howto``: This type is for shorter, task-oriented documents. It produces a simpler PDF without chapters, and is best for single-topic guides or tutorials. - -* ``toctree_only``: Boolean. If set to True, the ``startdocname`` document itself is not included in the output, only the documents referenced by the ``toctree`` directive are included. This is useful for creating a PDF-specific index file. - -For more details, see `latex_documents `_ in the Sphinx documentation. - - -Change PDF document filename -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -By default, the PDF output filename is derived from the ``project`` name in the :file:`conf.py` file: lowercase characters with blank spaces removed. - -To override the filename, update the second element (``targetname``) of the ``latex_documents`` tuple in :file:`conf.py`. The following example shows how to replace blank spaces in the project name with underscores: - -.. code-block:: python - - latex_documents = [ - ( - 'index', - f"{project.replace(' ', '_')}.tex", - '', - 'Author Name', - 'manual', - True, - ), - ] - -Change PDF document title -~~~~~~~~~~~~~~~~~~~~~~~~~ - -By default, the PDF title on the cover page comes from the title of the main index document. To override it, update the third element (title) of the ``latex_documents`` tuple in :file:`conf.py`. Use an empty string (``''``) to keep the default behaviour. - -Use a different index document for PDF builds -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Because the PDF output has a different usage and structure from the HTML output, it is sometimes useful to create a PDF-specific index document. For example, you may want to create a PDF-specific index file that includes only a subset of the pages in the HTML index. - -To use a different index document for PDF builds: - -1. Create a PDF-specific index document, for example, :file:`pdf-index.rst`. -2. Update the first element (``startdocname``) of the ``latex_documents`` tuple in :file:`conf.py` to point to the new index document. -3. Set the last element (``toctree_only``) of the ``latex_documents`` tuple in :file:`conf.py` to ``False`` to ensure only referenced documents are included in the PDF output. -4. Exclude the PDF-specific index document from the HTML build. This is done by changing the ``exclude_patterns`` list in :file:`conf.py`: - - .. code-block:: python - - # Identify the Sphinx builder being used - if '-b' in sys.argv: - builder = sys.argv[sys.argv.index('-b') + 1] - elif '-M' in sys.argv: - builder = sys.argv[sys.argv.index('-M') + 1] - else: - builder = 'html' # default builder - - # Exclude the PDF-specific index from the HTML build - if builder in ['html', 'dirhtml']: - exclude_patterns.append('pdf-index.rst') - -Check both the HTML and PDF outputs to confirm that different index documents are used for each output. - -.. note:: - The order and hierarchy of your ``toctree`` entries determine the chapters and sections in the PDF. - - Any headings placed before the main ``toctree`` in your root document will cause all referenced documents to be nested under that heading in the PDF. To avoid this, do not add extra headings before the ``toctree``. - - -Override the LaTeX template ------------------------------ - -The LaTeX template is a text file in the ``canonical-sphinx`` extension that provides the default styling and layout of the PDF document. The template contains a Python dictionary of LaTeX elements, which will be imported by Sphinx when the PDF is built. - -Any additions or changes to the default settings of LaTeX elements in the PDF document requires overriding the default template. - -1. Download the default template file `latex_elements_template.txt `_ from the ``canonical/canonical-sphinx`` GitHub repository, and save it to your project directory. For example, at :file:`.sphinx/latex_elements_custom.txt`. - -2. In the Python dictionary, add or modify the LaTeX elements you want to change. Details of changing the dictionary are covered in the sub-sections below. - -3. In your project :file:`conf.py`, add or update the ``latex_elements`` dictionary to load the local override of the LaTeX template. Change the file path to the location of your local override file. - -.. code-block:: python - - # Replace with the path to your local override file - latex_elements_file = ".sphinx/latex_elements_custom.txt" - - with open(latex_elements_file, "rt") as file: - latex_config = file.read() - if latex_elements == {}: - latex_elements = ast.literal_eval(latex_config) - -.. warning:: - - Defining other settings directly in ``latex_elements`` will override the values loaded from the template file or your local file. - - -Add more LaTeX packages to the preamble -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can use two methods to add additional LaTeX packages to the preamble: - -* Add the ``extrapackages`` key in your local template file: - - .. code-block:: python - :class: vale-ignore - :emphasize-lines: 3 - - { - ... - 'extrapackages': r'\usepackage{packagename}', - ... - } - -* Modify the values of the ``preamble`` key in your local template file. This is more flexible for adding LaTeX configurations and commands to the preamble. - -.. note:: - The format of the element values is a multi-line string, so use a raw string with the ``r`` prefix. - - -Remove the table of contents -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -For a short, compact document where navigation is not needed, you may want to remove the table of contents from the PDF output. - -To do this, provide a local copy of the default template file, and add a new key ``tableofcontents`` with an empty string as the value: - -.. code-block:: python - :emphasize-lines: 3 - - { - ... - 'tableofcontents': '', - ... - } - - -Include images or other assets -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If the local template requires additional images or other assets, for example, a custom title page or header, the file paths must be added to the Sphinx :file:`conf.py` file to be included in the PDF build. - -Provide a ``latex_additional_files`` variable in :file:`conf.py` as a list of file paths to the additional assets. If the variable already exists, add the new file paths to the list. The paths should be relative to the :file:`conf.py` file. - -.. code-block:: python - - # path relative to the conf.py file - latex_additional_files = [ - 'path/to/image.svg', - 'path/to/other-asset.pdf', - ] - -.. note:: - For better quality in the PDF output, it is recommended to use vector images (like SVG or PDF) rather than raster images (like PNG or JPEG). Raster images may lose quality when scaled up in the PDF. - - Do not use ``.tex`` as suffix, otherwise the file is processed as source files for the PDF build process. Instead, use ``.tex.txt`` or ``.sty`` to avoid conflicts with the LaTeX build process. - - -Use landscape layout -~~~~~~~~~~~~~~~~~~~~ - -The PDF output uses portrait orientation by default. To use landscape orientation, you need to add more packages to the LaTeX preamble and use a specific LaTeX environment to rotate the content. - -1. Add the ``extrapackages`` key to your local template file, and set the value to the ``pdflscape`` package: - - .. code-block:: python - :emphasize-lines: 3 - - { - ... - 'extrapackages': r'\usepackage{pdflscape}', - ... - } - - .. note:: - The format of the element values is a multi-line string, so use a raw string with the ``r`` prefix. - -2. Use the landscape environment in your documentation source file, and only in the PDF output. - - Wherever you want a section (such as a wide table or figure) to appear in the landscape view, use the ``.. raw:: latex`` directive to include raw LaTeX code that opens and closes the landscape environment. Only the content between ``\begin{landscape}`` and ``\end{landscape}`` will be rotated: - - .. code-block:: rst - - .. only:: latex - - .. raw:: latex - - \begin{landscape} - - .. list-table:: Example of a landscape table - :header-rows: 1 - - * - Column 1 - - Column 2 - - Column 3 - * - Data 1 - - Data 2 - - Data 3 - - .. only:: latex - - .. raw:: latex - - \end{landscape} - - -Check PDF build log files -------------------------- - -If you encounter an issue that requires further debugging, check the PDF build logs for more detailed error messages. The full logs are generated in the :file:`_build/latex` output directory, and then cleaned up after the build completes. - -To temporarily save the log files for debugging: - -1. Open the ``Makefile`` and locate the ``pdf`` target. Disable the cleanup step by commenting out the ``@rm -r $(BUILDDIR)/latex`` line. -2. Run the ``make pdf`` again. -3. Navigate to the output directory :file:`_build/latex` and check the ``*.log`` and ``*.tex`` files. -4. After debugging, restore the cleanup step by uncommenting the same line. - -.. warning:: - - Keeping the build log files from the previous build might cause conflicts with the current build - -Related -------- -- :ref:`build-and-preview` -- :ref:`configure-your-project` diff --git a/docs/how-to/optional-customisation/enable-google-analytics.rst b/docs/how-to/optional-customisation/enable-google-analytics.rst deleted file mode 100644 index 269e0e7f..00000000 --- a/docs/how-to/optional-customisation/enable-google-analytics.rst +++ /dev/null @@ -1,126 +0,0 @@ -.. meta:: - :description: How to enable Google Analytics in your project. - -.. _how-to-enable-google-analytics: - -Enable Google Analytics -======================= - -Many documentation sites collect page view and user behavior data with Google Analytics. -Collecting this data requires the user's consent. - -Once you're through with the guide, analytics will be collected on all public versions -of your documentation. - - -Add or update templates ------------------------ - -The header template inserts the Google Analytics tracking tag onto each page. If a user -consents to being tracked, their traffic and search data will be collected with each -page interaction. - -The footer template provides a link for users to change their data collection -preferences. - -The process for sourcing these files depends on your Starter Pack version. Check which -version is listed in your project's ``docs/.sphinx/version`` file. - - -On Starter Pack 1.6 or higher -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Starting in version 1.6 of the Starter Pack, these templates are available by default. -If you're on one of these versions, skip ahead to :ref:`update-your-configuration-file`. - - -On Starter Pack 1.5 or lower -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In version 1.5 of the Starter Pack and lower, the templates were sourced from a separate -repository. - -Download the latest version of the templates: - -- :literalref:`header.html ` -- :literalref:`footer.html ` - -Next, create a ``docs/_templates`` directory and move the templates into it. - -If you find that your project already has a ``header.html`` file, add the following HTML -immediately after the opening ``
    `` tag: - -.. code-block:: html - - - - -Similarly, if your project already has a ``footer.html`` file, add the following -highlighted line to the ``right-details`` div: - -.. code-block:: html - :emphasize-lines: 2 - -
    - Manage your tracker settings -
    - - -.. _update-your-configuration-file: - -Update your configuration file ------------------------------- - -Now that the templates are in place, you need to make Sphinx aware of them in your -project's configuration file. - -If you're on version 1.6 of the Starter Pack or higher, these lines already exist -in your configuration file. You only need to uncomment them in the following steps. In -lower versions, you need to add them yourself. - -Add or uncomment the following line: - -.. code-block:: python - :caption: conf.py - - templates_path = ["_templates"] - -The script and style sheet for the cookie banner are hosted remotely. Include them -in your docs by adding or uncommenting the following lines in the ``conf.py`` file: - -.. code-block:: python - :caption: conf.py - - html_css_files = ["https://assets.ubuntu.com/v1/d86746ef-cookie_banner.css"] - - html_js_files = ["https://assets.ubuntu.com/v1/287a5e8f-bundle.js"] - - -Test the cookie banner ----------------------- - -To verify that everything is working, run the following commands in the ``docs/`` -directory: - -.. code-block:: bash - - make clean - make install - make run - -You may need to clear your browser cache for changes to take effect. diff --git a/docs/how-to/optional-customisation/external-referencing-intersphinx.rst b/docs/how-to/optional-customisation/external-referencing-intersphinx.rst deleted file mode 100644 index e872647d..00000000 --- a/docs/how-to/optional-customisation/external-referencing-intersphinx.rst +++ /dev/null @@ -1,97 +0,0 @@ -.. meta:: - :description: Configure references to external Sphinx projects with the Intersphinx extension. - -.. _how-to-link-docs-intersphinx: - -Link to other documentation sets with Intersphinx -================================================= - -This guide provides instructions on how to set up external references using the Intersphinx extension. -Linking to external Sphinx-based documentation sets via hyperlinks is difficult to maintain. -Intersphinx provides a more robust alternative, linking to sections of other Sphinx projects based on -labels mapped out in an inventory list as ``objects.inv``. To effectively use Intersphinx, sections in -the target documentation set must have labels. - -Configure the extension ------------------------ - -In the ``conf.py`` file in your docs directory, add or enable ``sphinx.ext.intersphinx`` under ``extensions``: - -.. code-block:: python - :caption: conf.py - - extensions = [ - ... - "sphinx.ext.intersphinx", - ] - -Then, connect to the other project in the ``intersphinx_mapping`` -setting: - -.. code-block:: python - :caption: conf.py - - # Add configuration for intersphinx mapping - # Map only the Sphinx documentation sets that you need to link to from your docs set. - intersphinx_mapping = { - 'project-key': ('https://example.com', None) - } - -Replace ``project-key`` with the internal identifier for the project that you'll specify -in the document markup. For example, if the identifier were ``chisel``, an Intersphinx link to it would be ``:external+chisel:ref:`target```. - -The value after the URI points to a custom path location. If a project stores its ``objects.inv`` at a special location, replace ``None`` with the path to it. - -Check the external target labels --------------------------------- - -To check external target page labels, either search the project source code -manually or inspect the ``objects.inv`` file. In this file, each section has a -unique label. - -To inspect the file manually, run: - -.. code-block:: bash - - source .sphinx/venv/bin/activate - python -m sphinx.ext.intersphinx https://example.com/objects.inv - -The output lists the different pages and their labels: - -.. terminal:: - :output-only: - - lrd:doc - explanation/faq FAQ : explanation/faq/ - explanation/index Explanation : explanation/ - explanation/mode-of-operation How Chisel works : explanation/mode-of-operation/ - lrd:label - chise_faq FAQ : explanation/faq/#chise-faq - chisel-releases_ref chisel-releases : reference/chisel-releases/#chisel-releases-ref - chisel_helloworld_tutorial Getting started with Chisel : tutorial/getting-started/#chisel-helloworld-tutorial - std:doc - explanation/faq FAQ : explanation/faq/ - explanation/index Explanation : explanation/ - explanation/mode-of-operation How Chisel works : explanation/mode-of-operation/ - std:label - chise_faq FAQ : explanation/faq/#chise-faq - chisel-releases_ref chisel-releases : reference/chisel-releases/#chisel-releases-ref - chisel_helloworld_tutorial Getting started with Chisel : tutorial/getting-started/#chisel-helloworld-tutorial - -The appropriate labels are under ``std:label``. - -Add references to the text --------------------------- - -To add in-line references, follow this structure: - -.. list-table:: - :header-rows: 1 - :widths: 20 80 - - * - Format - - Syntax - * - reST - - ``:external+project_key:ref:`an_external_target``` - * - MyST - - ``{ref}`project_key:an_external_target``` diff --git a/docs/how-to/optional-customisation/index.rst b/docs/how-to/optional-customisation/index.rst deleted file mode 100644 index da1e053e..00000000 --- a/docs/how-to/optional-customisation/index.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. _optional-customisation: - -Optional customisation ------------------------- - -After the initial setup, you can customize your documentation to fit your project's needs. -This includes adding extensions, modifying the build process, and adding custom templates. - - -.. toctree:: - :maxdepth: 1 - - Bridge project and docs builds - Enable Google Analytics - Customise PDF output - Use Spread to test commands in documentation - Use custom HTML templates - Add Mermaid diagrams - Add Python docstrings - Add OpenAPI specifications - Add interactive tables - external-referencing-intersphinx - diff --git a/docs/how-to/optional-customisation/interactive-tables.rst b/docs/how-to/optional-customisation/interactive-tables.rst deleted file mode 100644 index b6e3a8fc..00000000 --- a/docs/how-to/optional-customisation/interactive-tables.rst +++ /dev/null @@ -1,43 +0,0 @@ -.. meta:: - :description: How to add interactive data tables to your project with sorting and filtering capabilities. - -.. _interactive-tables: - -Add interactive data tables -=========================== - -Data-heavy documentation often benefits from tables that users can explore interactively. -The `Sphinx DataTables`_ extension provides interactive tables where users can sort columns and filter rows, making large datasets more navigable and useful. -For examples, see the extension's documentation. - -The extension isn't available by default in the Starter Pack. To read more about table functionality that is available out of the box, see :ref:`Tables (MyST) ` and :ref:`Tables (reST) `. - -Include the ``sphinx-datatables`` extension -------------------------------------------- - -To include the extension in your documentation, add ``sphinx-datatables`` to ``docs/requirements.txt``. - -Then, add ``sphinx_datatables`` to the ``extensions`` list in ``docs/conf.py``. - -Make a table interactive by adding a special CSS class to the directive: - -.. tab-set:: - - .. tab-item:: reST - - .. code-block:: rst - - .. csv-table:: - :class: sphinx-datatable - :file: /reuse/animals.csv - :header-rows: 1 - - .. tab-item:: MyST - - .. code-block:: none - - ```{csv-table} - :class: sphinx-datatable - :file: /reuse/animals.csv - :header-rows: 1 - ``` diff --git a/docs/how-to/optional-customisation/mermaid-diagrams.md b/docs/how-to/optional-customisation/mermaid-diagrams.md deleted file mode 100644 index f9565e40..00000000 --- a/docs/how-to/optional-customisation/mermaid-diagrams.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -myst: - html_meta: - description: How to create and embed diagrams in your documentation using Mermaid. -relatedlinks: https://mermaid.js.org/intro/, https://mermaid.live/ ---- - -(howto-diagram-as-code-mermaid)= - -# Create diagrams as code using Mermaid - -Diagrams help users quickly understand and visualize complex ideas, but they can easily become outdated and difficult to maintain. -Creating diagrams as code solves this by keeping them alongside the software source, making updates and reviews simpler. - -Mermaid is a popular choice that allows diagrams to be created, maintained, and updated directly in the documentation. -This guide explains how to set up the {doc}`sphinxcontrib-mermaid ` extension and use Mermaid diagrams in your documentation, with examples included. - -```{note} -While there are many other tools and/or approaches for creating diagrams in visualizations in your documentation (e.g. [C4 model], [Dia], [PlantUML], [Structurizr], etc), we only provide support for `sphinxcontrib-mermaid` in the Starter Pack. -``` - -## Installation and setup - -First, add the "sphinxcontrib-mermaid" extension to {file}`requirements.txt` so that it's installed as part of your Sphinx project dependencies: - -```{code-block} text -:emphasize-lines: 6 -canonical-sphinx[full] -packaging -sphinxcontrib-svg2pdfconverter[CairoSVG] -sphinx-last-updated-by-git -sphinx-sitemap -sphinxcontrib-mermaid -``` - -Then add "sphinxcontrib.mermaid" in the "extensions" list in `conf.py`: - -```{code-block} python -extensions = [ - [...] - "sphinxcontrib.mermaid", -] -``` - -You are now ready embed Mermaid diagrams and visualization in your documentation using the `mermaid` directive. - -### Optional configuration - -You can further configure Mermaid's default settings in your project's {file}`conf.py`, such as specifying the image output format (e.g., "png", "raw"), enabling zoom on diagrams, or pinning the [Mermaid version] used for rendering. - -See [Mermaid configuration values] for more information. - -## Add a new diagram - -Use the `mermaid` directive to embed a Mermaid diagram into your documentation. -You start by declaring the type of diagram (e.g. "flowchart", "sequenceDiagram", "timeline", etc), followed by definition and contents. -It is also possible to specify additional configuration or custom styles, depending on the diagram type. - -Some examples will be covered below. - -```{seealso} -See the [Mermaid - Diagram syntax] reference for details on the syntax and customization options for each diagram type. -``` - -### Flowchart diagram with default settings - -The left-to-right flowchart below uses the default Mermaid settings. - -```{include} /reuse/mermaid.txt -:start-after: mermaid-diagram-flowchart-start -:end-before: mermaid-diagram-flowchart-end -``` - -### Timeline diagram with pre-defined theme - -The timeline diagram below uses a [pre-defined Mermaid theme]. - -```{include} /reuse/mermaid.txt -:start-after: mermaid-diagram-timeline-start -:end-before: mermaid-diagram-timeline-end -``` - -### Sequence diagram with global custom CSS - -The sequence diagram below has custom styling applied using a global CSS file. -A global CSS file enables the styles to be easily applied to all sequence diagrams, based on the classes defined in your stylesheet. -You can also use the global CSS file to customize the diagrams in dark mode. - -```{include} /reuse/mermaid.txt -:start-after: mermaid-diagram-sequence-start -:end-before: mermaid-diagram-sequence-end -``` - -### State diagram with image-specific styles - -The state diagram below has image-specific custom styling applied using the [`classDef` keyword]. - -```{include} /reuse/mermaid.txt -:start-after: mermaid-diagram-state-start -:end-before: mermaid-diagram-state-end -``` - -## Projects using Mermaid - -Here are some Canonical projects that use Mermaid for diagramming in their documentation: - -- [Checkbox](https://canonical-checkbox.readthedocs-hosted.com/stable/explanation/remote/) -- [cloud-init](https://docs.cloud-init.io/en/latest/explanation/boot.html) -- [Charmed MySQL K8s](https://canonical-charmed-mysql-k8s.readthedocs-hosted.com/8.0/explanation/flowcharts/) -- [Ubuntu Pro](https://documentation.ubuntu.com/pro/support-overview/) - -% LINKS - -[Mermaid version]: https://unpkg.com/browse/mermaid/ -[Mermaid configuration values]: https://sphinxcontrib-mermaid-demo.readthedocs.io/en/latest/#config-values -[Mermaid - Diagram syntax]: https://mermaid.js.org/intro/syntax-reference.html -[pre-defined Mermaid theme]: https://mermaid.js.org/syntax/timeline.html#themes -[`classDef` keyword]: https://mermaid.js.org/syntax/stateDiagram.html#styling-with-classdefs -[Official Mermaid documentation]: https://mermaid.js.org/intro/ -[Mermaid Live Editor]: https://mermaid.live/ -[C4 model]: https://c4model.com/ -[Dia]: http://dia-installer.de/ -[PlantUML]: https://plantuml.com/ -[Structurizr]: https://structurizr.com/ - diff --git a/docs/how-to/optional-customisation/openapi-specifications.rst b/docs/how-to/optional-customisation/openapi-specifications.rst deleted file mode 100644 index 0d580228..00000000 --- a/docs/how-to/optional-customisation/openapi-specifications.rst +++ /dev/null @@ -1,116 +0,0 @@ -.. meta:: - :description: How to add an OpenAPI integration to your project. - -.. _how-to-openapi: - -Add OpenAPI integration -======================= - -OpenAPI specifications provide a standardized way to document REST APIs. -This guide demonstrates how to add a minimal OpenAPI integration to your project using `Swagger UI `_, including a basic specification and an opt-in tag toggle based on a build-time environment variable to keep the documentation clean by default. - -Locate the specification ------------------------- - -The stub OpenAPI document can be found under ``docs/how-to/assets/openapi.yaml``. -You can use it as a starting point for your API description: - -.. literalinclude:: ../assets/openapi.yaml - :language: yaml - -Enable the viewer ------------------ - -The OpenAPI interactive viewer is disabled by default. -Exporting the ``OPENAPI`` environment variable when building in your terminal -makes Sphinx copy the specification to the output directory -and add an ``openapi`` tag that we can use in the documentation source:: - - export OPENAPI=1 - -Then rebuild the docs to pick up the specification:: - - make clean html - -.. tip:: - - Unset the variable to go back to the default build:: - - unset OPENAPI - - To enable it for a single command, prefix it like this:: - - OPENAPI=1 make clean html - -Confirm the viewer works ------------------------- - -Serve the documentation locally:: - - make run - -Navigate to ``/how-to/openapi/``. -When the feature flag is enabled, -the page renders the Swagger UI for the shipped specification right here. -The snippet that does this should be included in your documentation source -with the ``.. raw:: html`` directive: - -.. literalinclude:: ../assets/openapi._rst - :language: html - :lines: 2- - -.. only:: openapi - - When added, the snippet above renders the interactive viewer: - - .. include:: ../assets/openapi._rst - -.. only:: not openapi - - .. warning:: - - The interactive viewer is hidden now because ``OPENAPI`` was not set - when this documentation was built. - Export ``OPENAPI=1`` when building the documentation to see it here. - -Building on RTD ---------------- - -To enable the OpenAPI viewer on `Read the Docs `_ tentatively, -define the ``OPENAPI`` environment variable in your project's -`admin settings `_. - -If you're certain that you want the OpenAPI viewer enabled for all builds, -drop all conditional statements from ``conf.py`` and the reST files. -In ``conf.py``, replace the following lines:: - - html_extra_path = [] - - # ... - if os.getenv("OPENAPI", ""): - tags.add("openapi") - html_extra_path.append("how-to/assets/openapi.yaml") - - -With this:: - - html_extra_path = ["how-to/assets/openapi.yaml"] - - -Next, remove any tag-based logic from the reST files:: - - .. only:: openapi - -Troubleshooting ---------------- - -* The ``make html`` command fails with `unknown tag`: - Make sure you exported the environment variable - in the same shell session that runs ``make``. - -* The Swagger UI appears but cannot load the specification: - Make sure that ``openapi.yaml`` exists in the *root* of your build output - or adjust the import paths according to your build structure. - Also, overriding the ``html_extra_path`` setting in ``conf.py`` - may interfere with this configuration - because it is used to copy the specification to the output directory. diff --git a/docs/how-to/optional-customisation/python-docstrings.md b/docs/how-to/optional-customisation/python-docstrings.md deleted file mode 100644 index d548c6c9..00000000 --- a/docs/how-to/optional-customisation/python-docstrings.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -myst: - html_meta: - description: How to import Python docstrings automatically into your documentation using the Sphinx autodoc extension. ---- - -(sphinx-autodoc)= - -# Import docstrings with Sphinx `autodoc` - -Module and function details are useful reference material to have in documentation, but the process of manually pulling all the necessary details over can become tedious. The [Sphinx `autodoc` extension](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) provides the capability to automatically pull in docstrings and module information for Python code. - -## Prerequisites - -To use the Sphinx `autodoc` extension with the Starter Pack, you need: - -* Python module files located within the same repository as your documentation - -OR - -* The code repository added as a [Git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules) into the documentation repository - -## Setup - -In the {file}`conf.py` file in your docs directory, update the `sys.path` so that Sphinx can find your module files. At the top of the file, add a `sys.path.insert` that adds your `` directory: - -```{code-block} python -:caption: {file}`conf.py` - -import sys -from pathlib import Path - -relative_code_path = Path('..', '') -absolute_code_path = relative_code_path.resolve() -absolute_code_path_str = str(absolute_code_path) -sys.path.insert(0, absolute_code_path_str) # insert at index 0 so it occurs early in the list -``` - -Then, further down in the {file}`conf.py`, add `sphinx.ext.autodoc` to the list of extensions: - -```{code-block} python -:caption: {file}`conf.py` - -extensions = [ - ... - "sphinx.ext.autodoc", -] -``` - -## Usage - -See [Sphinx's `autodoc` instructions](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#usage) for details. - -## Known issues and limitations - -There are a few issues and limitations that should be taken into consideration. - -### Language - -The extension's usage is limited to Python code. There are extensions for some other languages but they have not been tested with the Starter Pack, such as [sphinxcontrib-rust](https://sphinxcontrib-rust.readthedocs.io/en/stable/) for Rust. - -### Docstring format - -The `autodoc` extension pulls the docstrings straight into the the reStructuredText (reST) document, which requires the docstrings to be in reST format. For docstrings in the Numpy or Google style, the [napoleon](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#module-sphinx.ext.napoleon) extension can convert the docstrings into reST prior to processing by `autodoc`. - -For documentation that is written in MyST Markdown, wrap the `eval-rst` directive around the `autodoc` calls: - -````{code-block} md - -```{eval-rst} - -.. py:currentmodule:: code. - -.. automodule:: - :members: - -``` -```` - -## Canonical examples - -```{list-table} Canonical autodoc examples -:header-rows: 1 - -* - Product - - {file}`conf.py` - - Raw Doc - - Rendered Doc - -* - Jubilant - - [conf.py](https://github.com/canonical/jubilant/blob/023ce73353352133c43dfb17b4a6cfad0f3e7816/docs/conf.py) - - [jubilant.rst](https://github.com/canonical/jubilant/blob/023ce73353352133c43dfb17b4a6cfad0f3e7816/docs/reference/jubilant.rst) - - [jubilant reference page](https://documentation.ubuntu.com/jubilant/reference/jubilant/) - -* - Ops - - [conf.py](https://github.com/canonical/operator/blob/main/docs/conf.py) - - [ops.rst](https://github.com/canonical/operator/blob/main/docs/reference/ops.rst) - - [*ops* reference page](https://documentation.ubuntu.com/ops/latest/reference/ops/) - -``` diff --git a/docs/how-to/publish-on-rtd.rst b/docs/how-to/publish-on-rtd.rst deleted file mode 100644 index 417a2760..00000000 --- a/docs/how-to/publish-on-rtd.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. meta:: - :description: How to publish your documentation on Read the Docs. - -.. _publish-on-rtd: - -Publish on Read the Docs -======================== - -Publishing your documentation on Read the Docs makes it available to a wider audience with automatic builds triggered by repository updates. -This guide walks you through the process of setting up your Starter Pack-based project on the Read the Docs platform. - -For Canonical-specific information on how to set up your documentation on Read the Docs, see the `Read the Docs at Canonical `_ and `How to publish documentation on Read the Docs `_ guides. - -In general, after enabling the Starter Pack for your documentation, follow these steps to build and publish your documentation on Read the Docs: - -1. Make sure your documentation :ref:`builds without errors or warnings `. -#. Log into Read the Docs. -#. In your account settings, navigate to :guilabel:`Connected services` and check that your GitHub account is listed. - If it's not listed, add a connection to GitHub. See `How to connect your Read the Docs account to your Git provider`_. -#. Use the `manual import`_ to create a project. -#. Specify the path to the :file:`.readthedocs.yaml` file for your build. - To do this, navigate to :guilabel:`Admin` > :guilabel:`Settings` and specify the path under "Path for ``.readthedocs.yaml``". - - For example, if your documentation folder is :file:`docs/`, specify the path as ``docs/.readthedocs.yaml``. -#. Update the relative paths in the :file:`.readthedocs.yaml` file to match the structure of your project. You might need to update the file paths specified in the following fields: - - * ``job.post_checkout`` - * ``sphinx.configuration`` - * ``python.install.requirements`` - -After this initial setup, your documentation should build successfully if your project is hosted from a public repository. -If you get any errors, check the build log for indications on what the problem is. - -If your project was imported from a private repository, your initial build will fail because Read the Docs won't have access to clone the repository. -You need to copy your project's public key from Read the Docs and add it as a deploy key to the repository, then re-run the build in Read the Docs. - -Configure the webhook ---------------------- - -If you have administrator privileges for the GitHub repository that you are adding, the integration webhook (which is responsible for automatically building the documentation when the repository changes) is created automatically. - -If you don't have administrator privileges, the webhook must be set up by someone who does. -The person with administrator privileges must have connected their Read the Docs account to GitHub. -See `How to connect your Read the Docs account to your Git provider`_. - -See `How to manually configure a Git repository integration`_ if you want to set up the webhook manually. - -Make your documentation public ------------------------------- - -By default, Read the Docs publishes your documentation for logged-in users only. - -To make the documentation public, you must configure the privacy level for each version of the documentation separately. -You can do this by navigating to the :guilabel:`Versions` tab and changing the :guilabel:`Privacy Level` for each version. - -Enable PR previews ------------------- - -To make Read the Docs automatically build your documentation when a pull request is opened or updated on GitHub, enable PR reviews for your project. - -To do so, navigate to :guilabel:`Admin` > :guilabel:`Settings` and select :guilabel:`Build pull requests for this project`. - -Read the Docs will then automatically build the documentation for each pull request, and the link to the output will be available as one of the checks in the pull request. diff --git a/docs/how-to/troubleshooting.rst b/docs/how-to/troubleshooting.rst deleted file mode 100644 index bb91c074..00000000 --- a/docs/how-to/troubleshooting.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. meta:: - :description: How to troubleshoot common issues with the Sphinx Starter Pack and Read the Docs. - -.. _troubleshooting: - -Troubleshooting -=================== - -This page provides guidance to resolve issues with the Starter Pack and Read the Docs -that are difficult to identify or that we don't expect to be solved. - - -Stable version won't build from the latest tag ----------------------------------------------- - -If your project has the ``stable`` version configured to build from tags, such as with -the default `semantic versioning behavior -`_, -your ``stable`` version can become out-of-step and continue building a particular tag, -even when the repository has newer tags. - - -Possible causes -~~~~~~~~~~~~~~~ - -An unwanted tag might have been pushed to the repository and then removed. Once -ReadTheDocs creates a version from a tag, it doesn't later verify that the tag still -exists, so the version will persist and become a zombie. - -If the unwanted tag is a higher iterator than any existing tag, the zombie version will -always take precedence. For example, if tag ``20.2.0`` was pushed by accident and then -replaced with ``2.20.0``, the corresponding version 20.2.0 will persist, and ``stable`` -will continue pointing to it. - - -Diagnosis -~~~~~~~~~ - -There's a roundabout procedure to verify whether your project is affected. Start by -opening your project dashboard on ReadTheDocs. - -On the **Builds** tab, locate the most recent ``stable`` build. For that version, hover -over the status indicator. In the hover box, open the **stable** link. If the resulting -GitHub page is a 404, then your project has a zombie version. - -.. image:: ../how-to/assets/troubleshoot-stable-zombie-version.png - -Resolution -~~~~~~~~~~ - -On your project dashboard, open the **Versions** tab and click **Add version**. - -Find the zombie version, deactivate it, then update it. - -Rebuild ``stable`` by retriggering it on the dashboard or pushing a new tag to the -repository. - - -Issue tracking -~~~~~~~~~~~~~~ - -`readthedocs/readthedocs.org#12450 -`_ diff --git a/docs/how-to/update-starter-packs/index.rst b/docs/how-to/update-starter-packs/index.rst deleted file mode 100644 index c1c785fd..00000000 --- a/docs/how-to/update-starter-packs/index.rst +++ /dev/null @@ -1,47 +0,0 @@ -.. meta:: - :description: Learn how to update your Sphinx Starter Pack with the latest features and improvements. - -.. _update-starter-packs: - -======================== -Update your Starter Pack -======================== - -The Starter Pack is updated frequently. After you copy its code and it becomes the documentation system in your project, you must manually maintain it. - -There are special pathways to bring in the latest features and improvements from the Starter Pack repository. - -Determine your current version ------------------------------- - -There are two versions of the Starter Pack that entail different update processes: - -- the **new**, or **extension-based** Starter Pack -- the **legacy**, or **pre-extension** Starter Pack - -New Starter Pack -^^^^^^^^^^^^^^^^^ - -If your :file:`conf.py` includes ``canonical-sphinx`` under the ``extensions`` list, you are using the new Starter Pack. - -To update a new Starter Pack project to the latest version, see: - -- :ref:`update-new-starter-pack` - -.. note:: - New Starter Pack releases use a semantic versioning scheme for minor and patch versions, which can be found in your project's :file:`.sphinx/version` file. - -Legacy Starter Pack -^^^^^^^^^^^^^^^^^^^^ - -If your :file:`conf.py` does _not_ include ``canonical-sphinx`` you are using the legacy Starter Pack. - -To update a legacy Starter Pack project to the latest version of the new Starter Pack: - -- :ref:`update-legacy-starter-pack` - -.. toctree:: - :hidden: - - New Starter Pack - Legacy Starter Pack diff --git a/docs/how-to/update-starter-packs/legacy-starter-pack.rst b/docs/how-to/update-starter-packs/legacy-starter-pack.rst deleted file mode 100644 index 07a299b0..00000000 --- a/docs/how-to/update-starter-packs/legacy-starter-pack.rst +++ /dev/null @@ -1,216 +0,0 @@ -.. meta:: - :description: Learn how to update Sphinx Starter Pack projects that don't yet use the canonical-sphinx extension. - -.. _update-legacy-starter-pack: - -Update the legacy Starter Pack -============================== - -This guide outlines the steps required to migrate a documentation project from the legacy Sphinx Documentation Starter Pack (*pre-extension* version) to the latest version that adopts the ``canonical-sphinx`` Sphinx extension. - -The extension-based documentation Starter Pack provides a set of features and configurations that are common across Canonical documentation projects. Key components, such as configuration and styling, are loaded as an add-on to your project. It can significantly reduce maintenance concerns when managing your documentation. - -.. note:: - If ``canonical-sphinx`` is included under ``extensions`` in your `conf.py`, - you are already using an extension-based starter-pack. Follow the guide on - :ref:`updating the new Starter Pack `. - -Update to the last pre-extension version ----------------------------------------- - -Update your documentation project to use the last pre-extension version of the Sphinx Documentation Starter Pack. Doing so will minimize the changes required during the migration by including the the latest features and configurations available in the pre-extension version. - -In your project repository, check out the `pre-extension release tag `_: - -.. code-block:: bash - - git checkout tags/pre-extension - -.. admonition:: Repository in detached HEAD state - :class: note - - Checking out a tag leaves your repository in a `detached HEAD state `_. Before proceeding, create a new branch: - - .. code-block:: bash - - git checkout -b migrate-to-extension - - -Set up a new project --------------------- - -1. Back up all existing files in your original documentation project. For example, you can rename the original ``docs/`` folder to ``docs_backup/``. - - .. warning:: - - If you proceed in the same directory, the following steps will overwrite some of the configuration files in the original project. - -2. Follow the steps in the :ref:`initial-setup` guide to initialise an empty project with the extension-based Starter Pack, at the original file path. - -3. Ensure the following files are at the root of your repository: - - - ``.github/workflows/*`` - -4. Ensure the following files are moved to their original paths in the project. These files are defaulted to the repository root, but may have be changed upon project needs: - - - ``.gitignore`` - - ``.readthedocs.yml`` - -5. Validate the project setup locally by running ``make run`` in the new project directory. - - -Migrate source files --------------------- - -The documentation Starter Pack has undergone breaking changes with the introduction of the ``canonical-sphinx`` extension. This section guides you through: - -- Configuration file changes -- Extension dependencies -- Documentation source migration - -For a complete list of the structural changes, refer to the `directory-structure-change`_ section. - -Sphinx configuration -~~~~~~~~~~~~~~~~~~~~~ - -A significant change in the new Starter Pack is the organisation of the configuration files, summarised in the following table: - -.. list-table:: - :widths: 20 40 40 - :header-rows: 1 - - * - Configuration file - - Pre-extension - - Extension-based - * - ``conf.py`` - - Common configurations shared by all Starter Pack projects - - Project-specific configurations - * - ``custom_conf.py`` - - Project-specific configuration - - Merged into ``conf.py`` and removed - -In the new Starter Pack, many common configurations are provided by the extension and are loaded automatically when building the documentation. ``docs/conf.py`` is the only configuration file, and it contains all project-specific configuration. Sensible defaults are set for general configuration by inclusion of the `canonical-sphinx` extension. - -Ensure that all the previous changes in the original ``custom_conf.py`` file are copied to the new ``conf.py`` file. - -Dependencies -~~~~~~~~~~~~ - -If your project requires additional extensions beyond the default list, add the extension list to the new project in ``docs/requirements.txt``. - -Documentation source files -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -1. Remove the Starter Pack's documentation files (``index.rst`` and any files in the ``docs/**/*`` sub-directory). - -2. Copy all documentation source files from your original project to the new project, keeping their original structure. These file may include but are not limited to: - - - ``.md`` - - ``.rst`` - - ``.txt`` - - ``.json`` - - images - - scripts - -3. Validate the migration by running ``make run``. - -Apply customisation -------------------- - -If your projects have custom configurations or styles, ensure that you identify and apply these changes to the new documentation project. - -For general information on customising the extension configuration, see :ref:`configure-your-project`. - -Static resources -~~~~~~~~~~~~~~~~ - -The extension provides a set of static resources, such as images, fonts, CSS files, and HTML templates, that are used to style the documentation for Canonical-branded design. These resources are bundled with the extension and are no longer provided as source files in the new Starter Pack. - -If you have customised any of these resources in the original project, you need to manually migrate these changes to the new project. - -For example, if you added customised styling in the original ``.sphinx/_static/custom.css`` file, follow the steps: - -1. Compare the changes between your customised file and the `default CSS file provided by the extension `_. This comparison helps you identify the changes that need to be migrated to the new project. -2. Create a new CSS file under ``docs/.sphinx/_static``. You can choose any other file location in the project directory, but it's recommended to keep the file structure similar to the original project. -3. Copy the additions and changes to the new empty file. -4. In the ``conf.py``, add the new files into the pre-defined ``html_css_files`` list variable to overwrite the default settings. -5. Build the documentation to verify that the customised styling is applied correctly. - - -.. _directory-structure-change: - -Directory structure changes ----------------------------- - -After you migrate to the extension, some directories and files are either deleted from the project or moved to a new location. - -Assuming that all previous documentation files were in the ``docs/`` sub-directory, the following list illustrates the changes in the directory structure after the migration. - -.. code-block:: text - - . - ├── .github - │ └── workflows - │ ├── automatic-doc-checks.yml - │ └── markdown-style-checks.yml - ├── .sphinx # moved to `docs/.sphinx` - │ ├── fonts # removed, files are part of the extension - │ │ ├── Ubuntu-B.ttf - │ │ ├── ubuntu-font-licence-1.0.txt - │ │ ├── UbuntuMono-B.ttf - │ │ ├── UbuntuMono-RI.ttf - │ │ ├── UbuntuMono-R.ttf - │ │ ├── Ubuntu-RI.ttf - │ │ └── Ubuntu-R.ttf - │ ├── images # removed, files are part of the extension - │ │ ├── Canonical-logo-4x.png - │ │ ├── front-page-light.pdf - │ │ ├── front-page.png - │ │ └── normal-page-footer.pdf - │ ├── _static # removed, files are part of the extension - │ │ ├── 404.svg - │ │ ├── custom.css - │ │ ├── favicon.png - │ │ ├── footer.css - │ │ ├── footer.js - │ │ ├── furo_colors.css - │ │ ├── github_issue_links.css - │ │ ├── github_issue_links.js - │ │ ├── header.css - │ │ ├── header-nav.js - │ │ └── tag.png - │ ├── _templates # removed, files are part of the extension - │ │ ├── sidebar - │ │ │ └── search.html - │ │ ├── 404.html - │ │ ├── base.html - │ │ ├── footer.html - │ │ ├── header.html - │ │ └── page.html - │ ├── build_requirements.py # removed - │ ├── get_vale_conf.py - │ ├── latex_elements_template.txt # removed, now part of the extension - │ ├── pa11y-ci.json # renamed to `pa11y.json` - │ └── spellingcheck.yaml - ├── metrics # removed - │ └── scripts - │ ├── build_metrics.sh - │ └── source_metrics.sh - ├── reuse # moved to `docs/reuse` - │ └── links.txt - ├── .custom_wordlist.txt # moved to `docs/.custom_wordlist.txt` - ├── .gitignore - ├── .readthedocs.yaml - ├── .wordlist.txt # moved to `docs/.sphinx/.wordlist.txt` - ├── .wokeignore # removed, check replaced by Vale - ├── conf.py # removed, now part of the extension - ├── custom_conf.py # renamed and moved to `docs/conf.py` - ├── doc-cheat-sheet-myst.md # moved to `docs/doc-cheat-sheet-myst.md` - ├── doc-cheat-sheet.rst # moved to `docs/doc-cheat-sheet.rst` - ├── index.rst # moved to `docs/index.rst` - ├── init.sh # removed - ├── make.bat # removed - ├── Makefile # moved to `docs/Makefile` - ├── Makefile.sp # removed - └── readme.rst # renamed to `README.rst` - diff --git a/docs/how-to/update-starter-packs/new-starter-pack.rst b/docs/how-to/update-starter-packs/new-starter-pack.rst deleted file mode 100644 index 7f1e0420..00000000 --- a/docs/how-to/update-starter-packs/new-starter-pack.rst +++ /dev/null @@ -1,164 +0,0 @@ -.. meta:: - :description: Learn how to update Sphinx Starter Pack projects that use the canonical-sphinx extension. - -.. _update-new-starter-pack: - -Update the new Starter Pack -=========================== - -The documentation Starter Pack is regularly updated to add features and address -bugs. You can transfer these improvements to your project by following these steps: - -- Clone the latest version of the Starter Pack -- Compare key files and directories in the Starter Pack to your project -- Transfer or delete relevant changes -- Confirm that your project builds correctly with the new changes - -This guide assumes your project has minimal customizations, and the repository -structure closely mirrors the Starter Pack's. Depending on your customizations, -you may need to take extra steps when updating. - -.. note:: - If ``canonical-sphinx`` is not included under ``extensions`` in your ``conf.py``, - your project is not on an extension-based starter-pack. Follow the guide on - :ref:`updating a legacy Starter Pack project `. - -Clone the Starter Pack repository ---------------------------------- -If you don't have a clean, local copy of the Starter Pack, clone it: - -.. code-block:: - - git clone https://github.com/canonical/sphinx-docs-starter-pack.git - -Confirm that both the Starter Pack's documentation and your project build with -no errors. - -.. important:: - Verify that your project still builds correctly after each key step. This - makes it easier to identify causes of build errors. - -Update the configuration and build files ----------------------------------------- -New Starter Pack versions often change the default configuration files. You'll -need to merge your project files with the config files from the new Starter Pack. -The recommended approach is to copy the customizations in your project to the starter -pack's config files and then replace your project's config files with the starter -pack's. - -The changes to be made vary between projects and updates. Therefore, this guide -cannot be overly prescriptive. - -``conf.py`` -~~~~~~~~~~~ -Rename your ``conf.py`` file to avoid overwriting it, and copy the Starter Pack's -version to the same location. Use a graphical diff tool such as `Kompare `_ -or `meld `_ to compare the old and new file and make the -following changes: - -- Copy your standard project details to the new ``conf.py`` file. These include: - - - Project and author names - - Ignored links - - Social links, etc. - -- Verify that the ``/static`` and ``/templates`` directories are located at the locations - specified by ``html_static_path`` and ``templates_path``, respectively, in the - new ``conf.py`` file. These should not be inside the ``/.sphinx`` directory. - -For other customizations, consider need and compatibility before copying them to -the new file. If it's not obvious whether you should copy over a customization -or include a new change, reach out to `Canonical's documentation team `_. - -``Makefile`` and ``.readthedocs.yaml`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Depending on the version of your project's Starter Pack, the new ``Makefile`` and ``.readthedocs.yaml`` -files may have few or no changes. Apply the same approach you used for ``conf.py`` -to merge your customizations into the new files. - -If there are no project-specific customizations in your files but there are changes -in the new ones, you can just overwrite your existing files with the new ones. - -Update the ``.sphinx`` directory --------------------------------- -In addition to the docs above, the ``/.sphinx`` directory is also likely to have some -changes in each update. These files are not intended to be modified by users. - -Unless you intentionally customized files in this directory, you can simply delete -your project's ``/.sphinx`` directory and replace it with the Starter Pack's. If there -are modifications in your project's ``/.sphinx`` directory, it is recommended that -they transfer them out. - -Review the remaining files --------------------------- -Some files in the Starter Pack may be updated less frequently, but it's a good idea -to review them during each update and determine if there are relevant changes: - -- Review ``requirements.txt``: If there are any updates, and your project's file - has no repository-specific requirements, you can overwrite the existing file - with the new one. If you added requirements based on your customizations be - sure to include them, e.g., ``sphinxext-rediraffe`` if you use rediraffe to - handle redirects. - -- Review the workflows in the ``/.github`` directory: If there are changes in the - following workflows, replace the existing files with the new ones. The starter - pack will have other workflows as well, but you'll need to decide whether your - project needs them or not: - - - Automatic doc checks - - CLA (contributor license agreement) check - - Check for removed URLs - - Markdown style check (only required for docs using markdown) - -- Review and transfer any necessary changes in the new ``.gitignore`` file to your - project. - -Build and test --------------- -Try building the docs locally and check the terminal output for errors:: - - make run - -To ensure the updated docs will pass CI checks when you make a pull request, run -the following commands and fix any errors reported: - -- ``make spelling`` -- ``make linkcheck`` -- ``make woke`` -- ``make lint-md`` (if you included the ``markdown-style-checks`` workflow) - -Troubleshooting errors ----------------------- -There is always the possibility of encountering build errors. Common causes -include: - -- Incorrect file locations or file paths -- Incompatible requirements in the new requirements file -- Missing customizations -- Cached build files - -When troubleshooting use the ``make clean`` command to ensure cached versions of -build files are not reused. - -Clean up --------- -There may be files that need to be deleted after the update such as starter-pack -specific files or files that have been replaced with newer versions: - -- If you haven't done so already, delete the copies of ``conf.py``, ``Makefile``, and - ``/.readthedocs.yaml`` that were renamed and replaced. -- If you did not strictly follow this guide for this or previous updates, it's - possible that you have some Starter Pack-specific files in your project. - These files can be safely deleted: - - - ``.github/pull_request_template.md`` - - ``.github/workflows/sphinx-python-dependency-build-checks.yml`` - - ``.github/CODEOWNERS`` - - ``.github/workflows/test-starter-pack.yml`` - -- These files can be deleted as long as they are not being used in your docs: - - - ``docs/reuse/links.txt`` - - ``docs/reuse/mermaid.txt`` - - ``docs/reuse/substitutions.txt`` - - ``docs/reuse/substitutions.yaml`` diff --git a/docs/index.rst b/docs/index.rst index 98c5785f..9a54f503 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,62 +1,43 @@ -Documentation starter pack -========================== - -The documentation starter pack helps you to quickly set up, build, and publish -documentation with Sphinx. - -It contains common styling and configuration through the `Canonical Sphinx`_ extension, -supports both |RST| and Markdown, and includes automatic documentation checks. + +============== In this documentation --------------------- -.. grid:: 1 1 2 2 - - .. grid-item-card:: Get started - :link: /set-up-a-new-project - :link-type: doc - - Set up the Sphinx starter pack in your project for the first time. - .. grid-item-card:: How-to guides - :link: /how-to/index - :link-type: doc +How this documentation is organized +----------------------------------- - **Step-by-step guides** - learn key operations and customisation. -.. grid:: 1 1 2 2 - - .. grid-item-card:: Reference - :link: /reference/index - :link-type: doc +Project and community +--------------------- - **Technical information** - review the automatic checks and Sphinx capabilities. - .. grid-item-card:: Explanation - :link: /explanation/index - :link-type: doc +Get involved +~~~~~~~~~~~~ - **Concepts** - understand the design and architecture of the starter pack. +Releases and support +~~~~~~~~~~~~~~~~~~~~ -Project and community ----------------------- -The Canonical Sphinx starter pack is an open source project that warmly welcomes community contributions, suggestions, fixes and constructive feedback. +Governance and policies +~~~~~~~~~~~~~~~~~~~~~~~ .. toctree:: :hidden: - :maxdepth: 2 + :maxdepth: 1 - Set up a new project - How-to guides - Reference - Explanation + tutorials/index + how-to/index + reference/index + explanation/index .. toctree:: :hidden: + :maxdepth: 1 - Release notes - Contribute + release-notes/index + contribute/index diff --git a/docs/redirects.txt b/docs/redirects.txt index 5b74bd15..cf8ae225 100644 --- a/docs/redirects.txt +++ b/docs/redirects.txt @@ -6,42 +6,3 @@ # 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/" "set-up-a-new-project" -"tutorial/set-up-automated-testing/" "how-to/optional-customisation/add-documentation-testing" -"tutorial/set-up/" "set-up-a-new-project" - -"how-to/customise/" "how-to/configure-your-project" -"how-to/rtd/" "how-to/publish-on-rtd" -"how-to/update/" "how-to" -"how-to/prereqs/" "how-to" -"how-to/build/" "how-to/build-and-preview" -"how-to/edit/" "set-up-a-new-project" -"how-to/guidance/" "how-to" -"how-to/migrate-from-pre-extension" "how-to/update-starter-packs/legacy-starter-pack" -"how-to/update-starter-packs/pre-extension" "how-to/update-starter-packs/legacy-starter-pack" -"how-to/bridge-project-and-doc-builds/" "how-to/optional-customisation/bridge-project-and-docs-builds" -"how-to/create-data-tables/" "how-to/optional-customisation/interactive-tables" -"how-to/custom-templates/" "how-to/optional-customisation/custom-html-templates" -"how-to/customise-pdf/" "how-to/optional-customisation/customise-pdf" -"how-to/diagrams-as-code-mermaid/" "how-to/optional-customisation/mermaid-diagrams" -"how-to/import-docstrings-with-autodoc/" "how-to/optional-customisation/" -"how-to/openapi/" "how-to/optional-customisation/openapi-specifications" -"how-to/troubleshoot-issues/" "how-to/troubleshooting" -"how-to/set-up-sitemaps/" "explanation/sitemaps" -"how-to/add-documentation-testing/" "how-to/optional-customisation/add-documentation-testing" -"how-to/test-ulwazi-theme/" "contribute/test-ulwazi-theme" -"how-to/enable-google-analytics/" "how-to/optional-customisation/enable-google-analytics" - -"reference/removed-url-check/" "reference/automatic_checks_removed-url-check" -"reference/myst-syntax-reference/" "reference/myst-syntax" -"reference/style-guide-myst/" "reference/myst-syntax" -"reference/doc-cheat-sheet-myst/" "reference/myst-syntax" -"reference/rst-syntax-reference/" "reference/rst-syntax" -"reference/style-guide/" "reference/rst-syntax" -"reference/doc-cheat-sheet/" "reference/rst-syntax" - -"reference/doc-cheat-sheet-myst" "reference/myst-syntax-reference" -"reference/style-guide-myst" "reference/myst-syntax-reference" -"reference/doc-cheat-sheet" "reference/rst-syntax-reference" -"reference/style-guide" "reference/rst-syntax-reference" diff --git a/docs/reference/automatic_checks.rst b/docs/reference/automatic_checks.rst deleted file mode 100644 index 2137de54..00000000 --- a/docs/reference/automatic_checks.rst +++ /dev/null @@ -1,108 +0,0 @@ -.. _automatic-checks: - -Automatic checks -================ - -The starter pack comes with several automatic checks that you can (and should!) run on your documentation before committing and pushing changes. - -The following checks are available: - -.. toctree:: - :maxdepth: 1 - :glob: - - /reference/automatic_checks_* - -Install prerequisite software ------------------------------ - -Some of the tools used by the automatic checks require ``npm``. Install ``npm`` using the appropriate method for your operating system through one of the following methods: - -* Your preferred package manager -* By following the `node version manager installation process `_ -* For Debian and Ubuntu Linux distributions, the ``sudo apt install npm`` command - -To install the validation tools: - -.. code-block:: bash - - make pa11y-install - make pymarkdownlnt-install # if using Markdown - -.. note:: - - `pa11y` is a non-blocking check in our current documentation workflow. - -Default GitHub actions ----------------------- - -The :literalref:`documentation-checks.yaml -` -workflow comes from the `documentation-workflows -`_ repository and supports the -following inputs. - -.. list-table:: - :header-rows: 1 - - * - Input - - Description - - Default - * - ``working-directory`` - - The root of the documentation project. This input is required. - - None - * - ``python-version`` - - The Python interpreter to use for the workflow's jobs. - - ``'3.10'`` - * - ``'fetch-depth'`` - - The number of commits to fetch from your repository. - - The full history is fetched. - * - ``runs-on`` - - The host system for the workflow's runners. - - ``'["ubuntu-24.04"]'`` - * - ``makefile`` - - The Makefile that checks are invoked from. - - ``'Makefile'`` - * - ``install-target`` - - The make target for installing required tools. - - ``'install'`` - * - ``spelling-target`` - - The make target to run for the spelling check. - - ``'spelling'`` - * - ``woke-target`` - - The make target to run for the inclusive language check - - ``'woke'`` - * - ``linkcheck-target`` - - The make target to run for the link check. - - ``'linkcheck'`` - -The current defaults force usage of Canonical-hosted runners, which some projects -may not be able to use. You may select your own runners by providing a ``runs-on`` -value, as shown by line 6 in the following example: - -.. code-block:: - :emphasize-lines: 6 - :linenos: - - jobs: - documentation-checks: - uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main - with: - working-directory: "docs" - runs-on: "ubuntu-22.04" - -Workflow triggers ------------------ - -For efficiency, the documentation check workflows are configured to run **only** when -changes are made to files in the ``docs/`` directory. If your project is structured -differently, or if you want to run the checks on other directories, modify the trigger -paths in the workflow files: - -.. code-block:: yaml - :emphasize-lines: 4 - - on: - pull_request: - paths: - - 'docs/**' # Only run on changes to the docs directory diff --git a/docs/reference/automatic_checks_accessibility.rst b/docs/reference/automatic_checks_accessibility.rst deleted file mode 100644 index 70dd4eaa..00000000 --- a/docs/reference/automatic_checks_accessibility.rst +++ /dev/null @@ -1,41 +0,0 @@ -.. _automatic-checks-accessibility: - -Accessibility check -=================== - -The accessibility check uses `Pa11y`_ to check for accessibility issues in the documentation output. - -It is configured to use the `Web Content Accessibility Guidelines (WCAG) 2.2`_, requiring `Level AA conformance`_. - -.. note:: - - This check is only available locally. - -Install prerequisite software ------------------------------ - -``Pa11y`` must be installed through ``npm``. If you need to install ``npm``, run the following command from any location on your system:: - - sudo apt install npm - -Once ``npm`` is installed, install ``Pa11y`` by running this command from within your documentation folder. - -.. code-block:: bash - - make pa11y-install - -Run the accessibility check ---------------------------- - -Run the following command from within your documentation folder. - -Look for accessibility issues in rendered documentation:: - - make pa11y - -Configure the accessibility check ---------------------------------- - -The :file:`pa11y.json` file in the :file:`.sphinx` folder provides basic defaults. - -To browse the available settings and options, see ``Pa11y``'s `README `_ on GitHub. diff --git a/docs/reference/automatic_checks_inclusivelanguage.rst b/docs/reference/automatic_checks_inclusivelanguage.rst deleted file mode 100644 index 4c7c7ece..00000000 --- a/docs/reference/automatic_checks_inclusivelanguage.rst +++ /dev/null @@ -1,80 +0,0 @@ -.. _automatic-checks-inclusivelanguage: - -Inclusive language check -======================== - -The inclusive language check uses `Vale`_ to check for violations of inclusive language guidelines. - -Run the inclusive language check --------------------------------- - -Run the following command from within your documentation folder:: - - make woke - -Configure the inclusive language check --------------------------------------- - -By default, the inclusive language check is applied to Markdown and |RST| files located in the documentation folder (usually :file:`docs/`). - -Inclusive language check exemptions ------------------------------------ - -Sometimes, you might need to use some non-inclusive words. -In such cases, you may exclude them from the check. - -Exempt a word in a single instance -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To exempt an individual word, give the word the ``woke-ignore`` role:: - - :woke-ignore:`` - -For instance:: - - This is your text. The word in question is here: :woke-ignore:`whitelist`. - -.. note:: - - Vale will lint the displayed text of a link, not the URL of a link. If you - wish to use a link that contains non-inclusive language, use appropriate link - text with the syntax appropriate for your source file. - -Exempt a word globally -~~~~~~~~~~~~~~~~~~~~~~ - -Vale will ignore any word listed in the ``.custom_wordlist.txt`` file. -To exempt a word, add it to this file globally. - -.. note:: - - Entries in ``.custom-wordlist`` are case-sensitive only when a capitalised word is used. For instance: - - - Adding ``kustom`` will cause all instances of ``Kustom`` and ``kustom`` to be ignored. - - Adding ``Kustom`` will cause only instances of ``Kustom`` to be ignored. - -Exclude multiple lines from a file -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Vale can be switched on and off within a file using syntax appropriate to that -format. - -To turn Vale off entirely for a section of Markdown:: - - - - This text will be ignored. - - - -.. important:: - - Only use this when other options are not suitable. - -To turn Vale off entirely for a section of |RST|:: - - .. vale off - - This text will be ignored. - - .. vale on \ No newline at end of file diff --git a/docs/reference/automatic_checks_links.rst b/docs/reference/automatic_checks_links.rst deleted file mode 100644 index 0edab55b..00000000 --- a/docs/reference/automatic_checks_links.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. _automatic-checks-links: - -Link check -========== - -The link check uses Sphinx to access the links in the documentation output and validate whether they are working. - -Run the link check ------------------- - -Run the following command from within your documentation folder. - -Validate links within the documentation:: - - make linkcheck - -Configure the link check ------------------------- - -If you have links in the documentation that you don't want to be checked (for example, because they are local links or give random errors even though they work), you can add them to the ``linkcheck_ignore`` variable in the :file:`conf.py` file. diff --git a/docs/reference/automatic_checks_linting.rst b/docs/reference/automatic_checks_linting.rst deleted file mode 100644 index ea83dea5..00000000 --- a/docs/reference/automatic_checks_linting.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. _automatic-checks-linting: - -Lint check -========== - -Markdown --------- - -The Markdown lint check is used to enforce standards and consistency in Markdown files. - -Run the lint check -~~~~~~~~~~~~~~~~~~ - -Run the following command from within your documentation folder to lint your Markdown files:: - - make lint-md - -Configure the lint check -~~~~~~~~~~~~~~~~~~~~~~~~ - -You can update the linting rules to enforce in the :file:`.sphinx/.pymarkdown.json` file. Refer to `the pymarkdown rules documentation `_ for all the available rules. diff --git a/docs/reference/automatic_checks_removed-url-check.rst b/docs/reference/automatic_checks_removed-url-check.rst deleted file mode 100644 index fc3522e3..00000000 --- a/docs/reference/automatic_checks_removed-url-check.rst +++ /dev/null @@ -1,14 +0,0 @@ -Check for removed URLs -====================== - -.. versionadded:: 1.2.0 - -The starter pack includes a GitHub action to -identify when page URLs have been removed. This includes moving pages to another -path, or removing them completely. - -This does not cover higher-level changes to URL paths, such as changing the RTD -project name, or language and versioning structure provided by RTD. - -This check is available to ensure that redirects are implemented when pages are -moved, or appropriate information can be provided when anything is removed. \ No newline at end of file diff --git a/docs/reference/automatic_checks_spelling.rst b/docs/reference/automatic_checks_spelling.rst deleted file mode 100644 index cafcd0c2..00000000 --- a/docs/reference/automatic_checks_spelling.rst +++ /dev/null @@ -1,38 +0,0 @@ -.. _reference-automatic-checks-spelling: - -Spelling check -============== - -The spelling check uses ``vale`` to check the spelling in your documentation. -It ignores code (both code blocks and inline code) and URLs (but it does check the link text). - -Run the spelling check ----------------------- - -Run the following commands from within your documentation folder. - -Ensure there are no spelling errors in the documentation:: - - make spelling - -Configure the spelling check ----------------------------- - -The Vale repository `includes a common list of words `_ that will be excluded from the check. -To add custom exceptions for your project, add them to the :file:`.custom_wordlist.txt` file. - - -.. _reference-automatic-checks-spelling-vale-ignore: - -Exclude specific terms ----------------------- - -Sometimes, you need to use a term in a specific context that should usually fail the spelling check. -(For example, you might need to refer to a product called ``ABC Docs``, but you do not want to add ``docs`` to the word list because it isn't a valid word.) - -In this case, you can use the ``:vale-ignore:`` role, and ensure your configuration file contains a class association in the ``rst_prolog``:: - - rst_prolog = """ - .. role:: vale-ignore - :class: vale-ignore - """ diff --git a/docs/reference/automatic_checks_styleguide.rst b/docs/reference/automatic_checks_styleguide.rst deleted file mode 100644 index 12255be4..00000000 --- a/docs/reference/automatic_checks_styleguide.rst +++ /dev/null @@ -1,112 +0,0 @@ -.. _automatic-checks-styleguide: - -Style guide linting -=================== - -The starter pack includes a method to run the `Vale`_ documentation linter configured with `the Vale rules for the current style guide `_. - - -Run the style guide linting ---------------------------- - -Run the following commands from within your documentation folder. - -Check documentation with Vale:: - - make vale - -Vale can run against individual files, folders, or globs. -To set a specific target:: - - make vale TARGET=example.file - make vale TARGET=example-folder - -.. note:: - - Running Vale against a folder will also run against its subfolders. - -You can use wildcards to run against all files matching a string, or an extension. - -For example, to run against all :code:`.md` files within a folder:: - - make vale TARGET=*.md - -To match, for example, :code:`doc_1.md` and :code:`doc_2.md`:: - - make vale TARGET=doc* - - -Exempt paragraphs ------------------ - -To disable Vale linting within individual files, specific markup can be used. - -For Markdown: - -.. code-block:: Markdown - - - - This text will be ignored by Vale. - - - -For |RST|: - -.. code-block:: rest - - .. vale off - - This text will be ignored by Vale. - - .. vale on - - -Exempt directives ------------------ - -To disable Vale linting for a specific directive, you can apply a class to the section. - -For Markdown: - -.. code-block:: Markdown - - ````{class} vale-ignore - ```{code-block} - - This content will be ignored by Vale. - ``` - ```` - -.. note:: - - This should not be necessary for Markdown, as Vale has an expanded scope for ignoring Markdown content by default. - -For |RST|: - -.. code-block:: rst - - .. class:: vale-ignore - .. code-block:: - - This content will be ignored by Vale. - -.. note:: - - The `.. class::` directive does not need to encapsulate content, it applies to the next logical block (which can be another directive or even a paragraph of content). - -Exempt words ------------- - -Use the ``:vale-ignore:`` role to ignore specific words inline, but first ensure your configuration file contains a class association in the ``rst_prolog``:: - - rst_prolog = """ - .. role:: vale-ignore - :class: vale-ignore - """ - -.. important:: - - The spelling check might still flag some terms that contain hyphens or spaces. - - For example, "Juju 3" was unable to be ignored by this method, and `needed to be added to the a specific exception within a rule `_. \ No newline at end of file diff --git a/docs/reference/default-extensions.rst b/docs/reference/default-extensions.rst deleted file mode 100644 index dfb1e5c1..00000000 --- a/docs/reference/default-extensions.rst +++ /dev/null @@ -1,85 +0,0 @@ -.. meta:: - :description: A list of extensions included in the starter pack by default. - -.. _reference-default-sphinx-extensions: - -Default Sphinx extensions -========================= - -These extensions are enabled in the Starter Pack by default. - -``canonical_sphinx`` - Contains the default Canonical branded theme. - -``notfound.extension`` - Allows creating custom 404 pages. - Needed by ``canonical_sphinx``. - -``sphinx_design`` - Provides UI components like responsive grids, cards, and badges. - - Needed by ``canonical_sphinx``. - -``sphinx_reredirects`` - Handles URL redirects for moved or deleted pages. - - Default Support for this extension will be dropped in an upcoming release of the - Starter Pack. Update your documentation to use ``sphinxext-rediraffe`` instead. - - Needed by ``canonical_sphinx``. - -``sphinx_tabs.tabs`` - Provides tabs. - - Needed by ``canonical_sphinx``. - -``sphinxcontrib.jquery`` - Ensures jQuery is loaded to maintain compatibility with older extensions and themes. - - Needed by ``canonical_sphinx``. - -``sphinxext.opengraph`` - Generates OpenGraph metadata to create rich preview cards when links are shared on social media. - - Needed by ``canonical_sphinx``. - -``sphinxext-rediraffe`` - Handles URL redirects for moved or deleted pages. Redirects can be defined as a - dictionary in the ``conf.py`` file or in a separate file. - -``sphinx.ext.intersphinx`` - Generates automatic links to the documentation objects of other Sphinx projects. - -``sphinx_config_options`` - Provides customized directives to easily document system or project configuration options. - -``sphinx_contributor_listing`` - Automatically generates a list of contributors to the project repository. - -``sphinx_filtered_toctree`` - Filters Table of Contents (``toctree``) entries based on specific tags or conditions. - -``sphinx_last_updated_by_git`` - Fetches and displays the accurate 'last updated' date for pages by reading Git commit metadata. - -``sphinx_related_links`` - Generates and injects a list of related links into documentation pages. - -``sphinx_roles`` - Provides custom inline text roles for standardized formatting or linking across the project. - -``sphinx_sitemap`` - Automatically generates a standard sitemap.xml file to improve indexing for search engine optimization (SEO). - -``sphinx_terminal`` - Renders styled terminal sessions and command-line output within the documentation. - -``sphinx_ubuntu_images`` - Generates lists of official Ubuntu disk images for specific release ranges and architectures. - -``sphinx_youtube_links`` - Provides a directive to embed YouTube videos into a page. - -``sphinxcontrib.cairosvgconverter`` - Converts SVG images into PDF. - diff --git a/docs/reference/include.txt b/docs/reference/include.txt deleted file mode 100644 index e59fdd84..00000000 --- a/docs/reference/include.txt +++ /dev/null @@ -1,3 +0,0 @@ -[include_start] -I feel included! -[include_end] diff --git a/docs/reference/index.rst b/docs/reference/index.rst index ea7a4305..2a21ad05 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -1,20 +1,4 @@ +.. _reference: + Reference ========= - -These documents provide an overview of different features of the starter pack. - -Also see the following information: - -- `Sphinx documentation starter pack repository`_ - -Contents --------- - -.. toctree:: - :maxdepth: 1 - - automatic_checks - default-extensions - rst-syntax - myst-syntax - diff --git a/docs/reference/myst-syntax.md b/docs/reference/myst-syntax.md deleted file mode 100644 index 93920910..00000000 --- a/docs/reference/myst-syntax.md +++ /dev/null @@ -1,977 +0,0 @@ ---- -relatedlinks: https://github.com/canonical/canonical-sphinx-extensions, [reStructuredText Primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html), [Canonical Documentation Style Guide](https://docs.ubuntu.com/styleguide/en) -myst: - substitutions: - advanced_reuse_key: "This is a substitution that includes a code block: - ``` - code block - ```" ---- - -(myst-syntax)= - -# MyST syntax - -The documentation files use a mixture of [Markdown](https://commonmark.org/) and [MyST](https://myst-parser.readthedocs.io/) syntax. - -See the following sections for syntax help and conventions. - -```{note} -This guide assumes that you are using the [Sphinx documentation starter pack](https://github.com/canonical/sphinx-docs-starter-pack). -Some of the mentioned syntax requires Sphinx extensions (which are enabled in the starter pack). -``` - -For general style conventions, see the [Canonical Documentation Style Guide](https://docs.ubuntu.com/styleguide/en). - -## Headings - -```{list-table} - :header-rows: 1 - -* - Input - - Description -* - `# Title` - - Page title and H1 heading -* - `## Heading` - - H2 heading -* - `### Heading` - - H3 heading -* - `#### Heading` - - H4 heading -* - ... - - Further headings -``` - -Adhere to the following conventions: - -- Do not use consecutive headings without intervening text. -- Do not skip levels (for example, do not follow an H2 heading with an H4 heading). -- Use sentence style for headings (capitalise only the first word). - -## Inline formatting - -```{list-table} - :header-rows: 1 - -* - Input - - Output -* - `` {guilabel}`UI element` `` - - {guilabel}`UI element` -* - `` `code` `` - - `code` -* - `` {file}`file path` `` - - {file}`file path` -* - `` {command}`command` `` - - {command}`command` -* - `` {kbd}`Key` `` - - {kbd}`Key` -* - `*Italic*` - - *Italic* -* - `**Bold**` - - **Bold** - -``` - -Adhere to the following conventions: - -- Use italics sparingly. Common uses for italics are titles and names (for example, when referring to a section title that you cannot link to, or when introducing the name for a concept). -- Use bold sparingly. Avoid using bold for emphasis and rather rewrite the sentence to get your point across. - -## Code blocks - -Start and end a code block with three back ticks: - - ``` - -You can specify the code language after the back ticks to enforce a specific lexer, but in many cases, the default lexer works just fine. - -`````{list-table} - :header-rows: 1 - -* - Input - - Output -* - ```` - - ``` - # Demonstrate a code block - code: - - example: true - ``` - - ```` - - - ``` - # Demonstrate a code block - code: - - example: true - ``` -* - ```` - - ```yaml - # Demonstrate a code block - code: - - example: true - ``` - - ```` - - - ```yaml - # Demonstrate a code block - code: - - example: true - - ``` - -````` - -To include back ticks in a code block, increase the number of surrounding back ticks: - -`````{list-table} - :header-rows: 1 - -* - Input - - Output -* - - ````` - - ```` - ``` - ```` - - ````` - - - - ```` - - ``` - - ```` - -````` - -### Terminal output - -A terminal view can be useful to show the output of a specific command, where it is -important to see the difference between input and output. In addition, including a -terminal view can help break up a long text and make it easier to consume, which is -especially useful when documenting command-line-only products. - -To show a terminal view, use the following directive: - -`````{list-table} - :header-rows: 1 - -* - Input - - Output -* - ````text - ```{terminal} - - input line 1 - input line 2 - - output line 1 - output line 2 - - output line 3 - ``` - ```` - - ```{terminal} - - input line 1 - input line 2 - - output line 1 - output line 2 - - output line 3 - ``` -````` - -By default, everything before the first blank line in the directive's content is -rendered as input, while any content that follows is rendered as output. The terminal -directive can only display one input command, but that command can span multiple lines, -as in the previous example. - -To render only the output of a command, include the `:output-only:` flag as a directive -option: - -`````{list-table} - :header-rows: 1 - -* - Input - - Output -* - ````text - ```{terminal} - :output-only: - - This is rendered as output. - ``` - ```` - - ```{terminal} - :output-only: - - This is rendered as output. - ``` -````` - -To customize the prompt (`user@host:~$` by default), specify any of the following options: - -* `:user:` -* `:host:` -* `:dir:` - -`````{list-table} - :header-rows: 1 - -* - Input - - Output -* - ````text - ```{terminal} - :user: author - :host: canonical - :dir: ~/path - - input - - output - ``` - ```` - - ```{terminal} - :user: author - :host: canonical - :dir: ~/path - - input - - output - ``` -````` - -The copy button for input commands is **opt-in**. You must include the `:copy:` flag -in the directive's options for the button to be displayed. - -To make the terminal scroll horizontally instead of wrapping long lines, include the `:scroll:` option. - -For more details, refer to the [`sphinx-terminal` README](https://github.com/canonical/sphinx-terminal/blob/main/README.md). - -## Links - -How to link depends on if you are linking to an external URL or to another page in the documentation. - -### External links - -For external links, use Markdown syntax. -You can also use just the URL, but this will usually cause issues with the spelling check, so you should specify the link text as code in this case. - -```{list-table} - :header-rows: 1 - -* - Input - - Output -* - `[Canonical website](https://canonical.com)` - - [Canonical website](https://canonical.com) -* - `https://canonical.com` - - [{spellexception}`https://canonical.com`](https://canonical.com) -* - ``[`https://canonical.com`](https://canonical.com)`` - - [`https://canonical.com`](https://canonical.com) -``` - -To display a URL as text and prevent it from being linked, add a ``: - -```{list-table} - :header-rows: 1 - -* - Input - - Output -* - `https://canonical.com` - - {spellexception}`https://canonical.com` - -``` - -#### Related links - -You can add links to related websites or Discourse topics to the sidebar - -To add a link to a related website, add the following field at the top of the page: - - relatedlinks: https://github.com/canonical/canonical-sphinx-extensions, [RTFM](https://www.google.com) - -To override the title, use Markdown syntax. Note that spaces are ignored; if you need spaces in the title, replace them with ` `, and include the value in quotes if Sphinx complains about the metadata value because it starts with `[`. - -To add a link to a Discourse topic, configure the Discourse instance in the {file}`conf.py` file. -Then add the following field at the top of the page (where `12345` is the ID of the Discourse topic): - - discourse: 12345 - -#### YouTube links - -To add a link to a YouTube video, use the following directive: - -`````{list-table} - :header-rows: 1 - -* - Input - - Output -* - ```` - - ```{youtube} https://www.youtube.com/watch?v=iMLiK1fX4I0 - :title: Demo - ``` - - ```` - - - ```{youtube} https://www.youtube.com/watch?v=iMLiK1fX4I0 - :title: Demo - ``` - -````` - -The video title is extracted automatically and displayed when hovering over the link. -To override the title, add the `:title:` option. - -### Internal references - -For internal references, both Markdown and MyST syntax are supported. In most cases, you should use MyST syntax though, because it resolves the link text automatically and gives an indication of the link in GitHub rendering. - -(a_section_target_myst)= - -#### Referencing a section - -To reference a section within the documentation (either on the same page or on another page), add a target to that section and reference that target. - -You can add targets at any place in the documentation. However, if there is no heading or title for the targeted element, you must specify a link text. - -(a_random_target_myst)= - -```{list-table} - :header-rows: 1 - :widths: 7 3 3 - -* - Input - - Output - - Description -* - `(target_ID)=` - - - - Adds the target ``target_ID``. -* - `` {ref}`a_section_target_myst` `` - - {ref}`a_section_target_myst` - - References a target that has a title. -* - `` {ref}`link text ` `` - - {ref}`link text ` - - References a target and specifies a title. -* - `` {ref}`project_key:an_external_target` `` - - Default link text - - You can also reference targets in other Sphinx projects. `project-key` must be a key in the `intersphinx_mapping` dictionary in `conf.py`. The link text defaults to the target's title. -* - ``[`xyz`](a_random_target_myst)`` - - [`xyz`](a_random_target_myst) - - Use Markdown syntax if you need markup on the link text. -``` - -Adhere to the following conventions: - -- Never use external links to reference a section in the same doc set or a doc set that is linked with Intersphinx. It would likely cause a broken link in the future. -- Override the link text only when it is necessary. If you can use the section title as link text, do so, because the text will then update automatically if the title changes. -- Never "override" the link text with the same text that would be generated automatically. - -#### Referencing a page - -If a documentation page does not have a target, you can still reference it by using the `{doc}` role with the file name and path. -Use MyST syntax to automatically extract the link text. When overriding the link text, use Markdown syntax. - -```{list-table} - :header-rows: 1 - -* - Input - - Output - - Status -* - `` {doc}`index` `` - - {doc}`index` - - Preferred. -* - `[](index)` - - [](index) - - Do not use. -* - `[Index page](index)` - - [Index page](index) - - Preferred when overriding the link text. -* - `` {doc}`Index page ` `` - - {doc}`Index page ` - - Alternative when overriding the link text. -``` - -Adhere to the following conventions: - -- Only use the `{doc}` role when you cannot use the `{ref}` role, thus only if there is no target at the top of the file and you cannot add it. When using the `{doc}` role, your reference will break when a file is renamed or moved. -- Override the link text only when it is necessary. If you can use the document title as link text, do so, because the text will then update automatically if the title changes. -- Never "override" the link text with the same text that would be generated automatically. - -## Navigation - -Every documentation page must be included as a sub-page to another page in the navigation. - -This is achieved with the [`toctree`](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree) directive in the parent page: - -```` -```{toctree} -:hidden: - -sub-page1 -sub-page2 -``` -```` - -If a page should not be included in the navigation, you can suppress the resulting build warning by putting the following instruction at the top of the file: - -``` ---- -orphan: true ---- -``` - -Use orphan pages sparingly and only if there is a clear reason for it. - -```{tip} -Instead of hiding pages that you do not want to include in the documentation from the navigation, you can exclude them from being built. -This method will also prevent them from being found through the search. - -To exclude pages from the build, add them to the `custom_excludes` variable in the {file}`conf.py` file. -``` - -## Lists - -````{list-table} - :header-rows: 1 - -* - Input - - Output -* - ``` - - Item 1 - - Item 2 - - Item 3 - ``` - - - Item 1 - - Item 2 - - Item 3 -* - ``` - 1. Step 1 - 1. Step 2 - 1. Step 3 - ``` - - 1. Step 1 - 1. Step 2 - 1. Step 3 -* - ``` - 1. Step 1 - - Item 1 - * Sub-item - - Item 2 - 1. Step 2 - 1. Sub-step 1 - 1. Sub-step 2 - ``` - - 1. Step 1 - - Item 1 - * Sub-item - - Item 2 - 1. Step 2 - 1. Sub-step 1 - 1. Sub-step 2 -```` - -Adhere to the following conventions: - -- In numbered lists, use `1.` for all items to generate the step numbers automatically. - You can also use a higher number for the first item to start with that number. -- Use `-` for unordered lists. When using nested lists, you can use `*` for the nested level. - -### Definition lists - -````{list-table} - :header-rows: 1 - -* - Input - - Output -* - ``` - Term 1 - : Definition - - Term 2 - : Definition - ``` - - Term 1 - : Definition - - Term 2 - : Definition -```` - -(myst_style_guide_tables)= - -## Tables - -You can use standard Markdown tables. However, using the reST [list table](https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table) syntax is usually much easier. -See the [Sphinx documentation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#table-directives) for all table syntax alternatives. - -Both markups result in the following output: - -```{list-table} - :header-rows: 1 - -* - Header 1 - - Header 2 -* - Cell 1 - - Second paragraph cell 1 - - Cell 2 -* - Cell 3 - - Cell 4 -``` - -### Markdown tables - -``` -| Header 1 | Header 2 | -|------------------------------------|----------| -| Cell 1

    2nd paragraph cell 1 | Cell 2 | -| Cell 3 | Cell 4 | -``` - -### List tables - -See [list tables](https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table) for reference. - -```` -```{list-table} - :header-rows: 1 - -* - Header 1 - - Header 2 -* - Cell 1 - - 2nd paragraph cell 1 - - Cell 2 -* - Cell 3 - - Cell 4 -``` -```` - -### Data tables - -If you have a small amount of CSV data, you can include the data in the doc source. - -For example: - -```` -```{csv-table} -:header-rows: 1 - -"Animal", "Number of legs", "Size" - -"Worm", 0, "Small" -"Penguin", 2, "Medium" -"Horse", 4, "Large" -"Ant", 6, "Small" -"Octopus", 8, "Medium" -``` -```` - -If you have a large amount of CSV data, or the data is generated by an automated process, -you can include the data from a file. - -For example: - -```` -```{csv-table} -:file: /reuse/animals.csv -:header-rows: 1 -``` -```` - -Both markups result in the following output: - -```{csv-table} -:header-rows: 1 - -"Animal", "Number of legs", "Size" - -"Worm", 0, "Small" -"Penguin", 2, "Medium" -"Horse", 4, "Large" -"Ant", 6, "Small" -"Octopus", 8, "Medium" -``` - -Customize the column widths, character encoding, and so on, as described in the -[`csv-table` reference](https://mystmd.org/guide/directives#directive-csv-table). - -The starter pack can also render interactive tables. See: {ref}`interactive-tables`. - -## Notes - -`````{list-table} - :header-rows: 1 - -* - Input - - Output -* - ```` - ```{note} - A note. - ``` - ```` - - ```{note} - A note. - ``` -* - ```` - ```{tip} - A tip. - ``` - ```` - - ```{tip} - A tip. - ``` -* - ```` - ```{important} - Important information - ``` - ```` - - ```{important} - Important information. - ``` -* - ```` - ```{caution} - This might damage your hardware! - ``` - ```` - - ```{caution} - This might damage your hardware! - ``` -````` - -Adhere to the following conventions: - -- Use notes sparingly. -- Only use the following note types: `note`, `tip`, `important`, `caution` -- Only use a caution if there is a clear hazard of hardware damage or data loss. - -## Images - -````{list-table} - :header-rows: 1 - -* - Input - - Output -* - ``` - ![Alt text](https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png) - ``` - - ![Alt text](https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png) -* - ```` - ```{figure} https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png - :width: 100px - :alt: Alt text - - Figure caption - ``` - ```` - - ```{figure} https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png - :width: 100px - :alt: Alt text - - Figure caption - ``` -```` - -Adhere to the following conventions: - -- For local pictures, start the path with `/` (for example, `/images/image.png`). -- Use `PNG` format for screenshots and `SVG` format for graphics. -- See [Five golden rules for compliant alt text](https://abilitynet.org.uk/resources/digital-accessibility/five-golden-rules-compliant-alt-text) for information about how to word the alt text. - -## Reuse - -A big advantage of MyST in comparison to plain Markdown is that it allows to reuse content. - -### Substitution - -To reuse sentences or paragraphs that have little markup and special formatting, use [substitutions](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions). - -Substitutions can be defined in the following locations: - -- Globally, in a file named {file}`reuse/substitutions.yaml` that is loaded into the [`myst_substitutions`](https://myst-parser.readthedocs.io/en/v0.13.5/using/syntax-optional.html#substitutions-with-jinja2) variable in {file}`conf.py`: - - ```{code-block} python - :caption: "{spellexception}`conf.py`" - - import os - import yaml - - ... - - if os.path.exists('./reuse/substitutions.yaml'): - with open('./reuse/substitutions.yaml', 'r') as fd: - myst_substitutions = yaml.safe_load(fd.read()) - ``` - - ```{code-block} yaml - :caption: "{spellexception}`reuse/substitutions.yaml`" - - # Key/value substitutions to use within the Sphinx doc. - {version_number: "0.1.0", - formatted_text: "*Multi-line* text\n that uses basic **markup**.", - site_link: "[Website link](https://example.com)"} -- Locally, putting the definitions at the top of a single file in the following format: - - ```` - --- - myst: - substitutions: - version_number: "0.1.0" - formatted_text: "*Multi-line* text - that uses basic **markup**." - advanced_reuse_key: "This is a substitution that includes a code block: - ``` - code block - ```" - - --- - ```` - -You can combine both options by defining a default substitution in `reuse/substitutions.py` and overriding it at the top of a file. - -The definitions from the above examples are rendered as follows: - -```{list-table} - :header-rows: 1 - -* - Input - - Output -* - `{{version_number}}` - - {{version_number}} -* - `{{formatted_text}}` - - {{formatted_text}} -* - `{{site_link}}` - - {{site_link}} -* - `{{advanced_reuse_key}}` - - {{advanced_reuse_key}} -``` - -Adhere to the following convention: - -- Substitutions do not work on GitHub. Therefore, use substitution names that indicate the included content (for example, `note_not_supported` instead of `reuse_note`). - -### File inclusion - -To reuse longer sections or text with more advanced markup, you can put the content in a separate file and include the file or parts of the file in several locations. - -To select parts of the text in a file, use `:start-after:` and `:end-before:` if possible. You can combine those with `:start-line:` and `:end-line:` if required (if the same text occurs more than once). Using only `:start-line:` and `:end-line:` is error-prone though. - -You cannot put any targets into the content that is being reused (because references to this target would be ambiguous then). You can, however, put a target right before including the file. - -By combining file inclusion and substitutions, you can even replace parts of the included text. - -`````{list-table} - :header-rows: 1 - -* - Input - - Output -* - ```` - - % Include parts of the content from - % file rst-syntax.rst - ```{include} rst-syntax.rst - :start-after: "Adhere to the following conventions:" - :end-before: " Use the ones specified above." - ``` - - ```` - - - - % Include parts of the content from file [rst-syntax.rst](rst-syntax.rst) - ```{include} rst-syntax.rst - :start-after: "Adhere to the following conventions:" - :end-before: " Use the ones specified above." - ``` - -````` - -Adhere to the following convention: - -- File inclusion does not work on GitHub. Therefore, always add a comment linking to the included file. -- Files that only contain text that is reused somewhere else should be placed in the {file}`reuse` folder and end with the extension ``.txt`` to distinguish them from normal content files. -- To make sure inclusions don't break, consider adding HTML comments (``) to the source file as markers for starting and ending. - -## Tabs - -The recommended way of creating tabs is to use the tabs that the [Sphinx design](https://sphinx-design.readthedocs.io/en/latest/) extension provides. - -``````{list-table} - :header-rows: 1 - -* - Input - - Output -* - ````` - - ````{tab-set} - - ```{tab-item} Tab 1 - :sync: key1 - - Content Tab 1 - ``` - - ```{tab-item} Tab 2 - :sync: key2 - - Content Tab 2 - ``` - - ```` - - ````` - - - ````{tab-set} - - ```{tab-item} Tab 1 - :sync: key1 - - Content Tab 1 - ``` - - ```{tab-item} Tab 2 - :sync: key2 - - Content Tab 2 - ``` - ```` -`````` - -Alternatively, you can use the [Sphinx tabs](https://sphinx-tabs.readthedocs.io/en/latest/) extension, which is also enabled by default. This was previously recommended due to limitations in Sphinx Design that are now fixed. - -``````{list-table} - :header-rows: 1 - -* - Input - - Output -* - ````` - - ````{tabs} - - ```{group-tab} Tab 1 - - Content Tab 1 - ``` - - ```{group-tab} Tab 2 - - Content Tab 2 - ``` - - ```` - - ````` - - - ````{tabs} - - ```{group-tab} Tab 1 - - Content Tab 1 - ``` - - ```{group-tab} Tab 2 - - Content Tab 2 - ``` - ```` -`````` - -## Collapsible sections - -There is no support for details sections in MyST, but you can insert HTML to create them. - -````{list-table} - :header-rows: 1 - -* - Input - - Output -* - ``` -
    - Details - - Content -
    - ``` - - -
    - Details - - Content -
    - -```` - -## Glossary - -You can define glossary terms in any file. Ideally, all terms should be collected in one glossary file though, and they can then be referenced from any file. - -`````{list-table} - :header-rows: 1 - -* - Input - - Output -* - ```` - - ```{glossary} - - MyST example term - Definition of the example term. - ``` - - ```` - - - ```{glossary} - - MyST example term - Definition of the example term. - ``` - -* - ``{term}`MyST example term` `` - - {term}`MyST example term` -````` - -## More useful markup - -`````{list-table} - :header-rows: 1 - -* - Input - - Output - - Description -* - ```` - - ```{versionadded} X.Y - ``` - - ```` - - ```{versionadded} X.Y - ``` - - Can be used to distinguish between different versions. -* - ``` - --- - ``` - - A horizontal line - - Can be used to visually divide sections on a page. -* - ``` - - ``` - - - - Not visible in the output. -* - ``` - {abbr}`API (Application Programming Interface)` - ``` - - {abbr}`API (Application Programming Interface)` - - Hover to display the full term. -* - ``` - {spellexception}`PurposelyWrong` - ``` - - {spellexception}`PurposelyWrong` - - Explicitly exempt a term from the spelling check. - -````` diff --git a/docs/reference/rst-syntax.rst b/docs/reference/rst-syntax.rst deleted file mode 100644 index 88558f38..00000000 --- a/docs/reference/rst-syntax.rst +++ /dev/null @@ -1,989 +0,0 @@ -:relatedlinks: https://github.com/canonical/lxd-sphinx-extensions, [reStructuredText Primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html), [Canonical Documentation Style Guide](https://docs.ubuntu.com/styleguide/en) - -.. _rst-syntax: - -reStructuredText syntax -======================= - -The documentation files use `reStructuredText`_ (reST) syntax. - -See the following sections for syntax help and conventions. - -.. note:: - This guide assumes that you are using the `Sphinx documentation starter pack`_. - Some of the mentioned syntax requires Sphinx extensions (which are enabled in the starter pack). - -For general style conventions, see the `Canonical Documentation Style Guide`_. - -Headings --------- - -.. list-table:: - :header-rows: 1 - - * - Input - - Description - * - .. code:: - - Title - ===== - - Page title and H1 heading - * - .. code:: - - Heading - ------- - - H2 heading - * - .. code:: - - Heading - ~~~~~~~ - - H3 heading - * - .. code:: - - Heading - ^^^^^^^ - - H4 heading - * - .. code:: - - Heading - ....... - - H5 heading - -Underlines must be at least as long as the title or heading. - -Adhere to the following conventions: - -- Do not use consecutive headings without intervening text. -- Be consistent with the characters you use for each level. - Use the ones specified above. -- Use sentence style for headings (capitalise only the first word). - -Inline formatting ------------------ - -.. list-table:: - :header-rows: 1 - - * - Input - - Output - * - ``:guilabel:`UI element``` - - :guilabel:`UI element` - * - ````code```` - - ``code`` - * - ``:file:`file path``` - - :file:`file path` - * - ``:command:`command``` - - :command:`command` - * - ``:kbd:`Key``` - - :kbd:`Key` - * - ``*Italic*`` - - *Italic* - * - ``**Bold**`` - - **Bold** - -Adhere to the following conventions: - -- Use italics sparingly. Common uses for italics are titles and names (for example, when referring to a section title that you cannot link to, or when introducing the name for a concept). -- Use bold sparingly. Avoid using bold for emphasis and rather rewrite the sentence to get your point across. - -Code blocks ------------ - -To start a code block, either end the introductory paragraph with two colons (``::``) and indent the following code block, or explicitly start a code block with ``.. code::``. -In both cases, the code block must be surrounded by empty lines. - -When explicitly starting a code block, you can specify the code language to enforce a specific lexer, but in many cases, the default lexer works just fine. - -For a list of supported languages and their respective lexers, see the official `Pygments documentation`_. - -.. list-table:: - :header-rows: 1 - - * - Input - - Output - * - .. code:: - - Demonstrate a code block:: - - code: - - example: true - - Demonstrate a code block:: - - code: - - example: true - * - .. code:: - - .. code:: - - # Demonstrate a code block - code: - - example: true - - .. code:: - - # Demonstrate a code block - code: - - example: true - * - .. code:: - - .. code:: yaml - - # Demonstrate a code block - code: - - example: true - - .. code:: yaml - - # Demonstrate a code block - code: - - example: true - -Terminal output -~~~~~~~~~~~~~~~ - -A terminal view can be useful to show the output of a specific command, where it is -important to see the difference between input and output. In addition, including a -terminal view can help break up a long text and make it easier to consume, which is -especially useful when documenting command-line-only products. - -To include a terminal view, use the following directive: - -.. list-table:: - :header-rows: 1 - - * - Input - - Output - * - .. code-block:: text - - .. terminal:: - - input line 1 - input line 2 - - output line 1 - output line 2 - - output line 3 - - .. terminal:: - - input line 1 - input line 2 - - output line 1 - output line 2 - - output line 3 - -By default, everything before the first blank line in the directive's content is -rendered as input, while any content that follows is rendered as output. The terminal -directive can only display one input command, but that command can span multiple lines, -as in the previous example. - -To render only the output of a command, include the ``:output-only:`` flag in the -directive's options: - -.. list-table:: - :header-rows: 1 - - * - Input - - Output - * - .. code-block:: text - - .. terminal:: - :output-only: - - This is rendered as output. - - - .. terminal:: - :output-only: - - This is rendered as output. - -To customize the prompt (``user@host:~$`` by default), specify any of the following options: - -* ``:user:`` -* ``:host:`` -* ``:dir:`` - -.. list-table:: - :header-rows: 1 - - * - Input - - Output - * - .. code-block:: text - - .. terminal:: - :user: author - :host: canonical - :dir: ~/path - - input - - output - - .. terminal:: - :user: author - :host: canonical - :dir: ~/path - - input - - output - -The copy button for input commands is **opt-in**. You must include the ``:copy:`` flag -in the directive's options for the button to be displayed. - -To make the terminal scroll horizontally instead of wrapping long lines, include the ``:scroll:`` option. - -For more details, refer to the `sphinx-terminal README `_. - -Links ------ - -Link markup depends on whether you need an external URL -or a page in the same documentation set. - - -External links -~~~~~~~~~~~~~~ - -For external links, use one of the following methods. - -Link inline: - Define occasional links directly within the surrounding text. - To make the link text show up in code-style (which excludes it from the spelling check), use the ``:literalref:`` role. - - .. list-table:: - :header-rows: 1 - - * - Input - - Output - - * - ```Canonical website `_`` - - `Canonical website `_ - - * - ``:literalref:`ubuntu.com``` - - :literalref:`ubuntu.com` - * - ``:literalref:`xyzcommand ``` - - :literalref:`xyzcommand ` - - You can also use a URL as is (``https://example.com``), - but that might cause spellchecker errors. - - .. tip:: - - To prevent a URL from appearing as a link, - add an escaped space character (``https:\ //``). - The space won't be rendered: - - .. list-table:: - :header-rows: 1 - - * - Input - - Output - - * - ``https:\ //canonical.com/`` - - :spellexception:`https://canonical.com/` - - -Define the links at the bottom of the page: - To keep the text readable, group the link definitions below. - - .. list-table:: - :header-rows: 1 - - * - Input - - Output - - Description - - * - ```Canonical website`_`` - - `Canonical website`_ - - Using the below defined link - - * - .. code:: - - .. LINKS - .. _Canonical website: https://canonical.com/ - - *n/a* - - Defining links at the bottom - - -Define the links in a shared file: - To keep the text readable and links maintainable, - put all link definitions in a file named :file:`reuse/links.txt` - to include it in a custom ``rst_epilog`` directive - (see the `Sphinx documentation `_). - - .. code-block:: python - :caption: :spellexception:`conf.py` - - custom_rst_epilog = """ - .. include:: reuse/links.txt - """ - - .. list-table:: - :header-rows: 1 - - * - Input - - Output - - * - ```Canonical website`_`` - - `Canonical website`_ - -Related links -^^^^^^^^^^^^^ - -You can add links to related websites or Discourse topics to the sidebar. - -To add a link to a related website, add the following field at the top of the page:: - - :relatedlinks: https://github.com/canonical/lxd-sphinx-extensions, [RTFM](https://www.google.com) - -To override the title, use Markdown syntax. Note that spaces are ignored; if you need spaces in the title, replace them with `` ``, and include the value in quotes if Sphinx complains about the metadata value because it starts with ``[``. - -To add a link to a Discourse topic, configure the Discourse instance in the :file:`conf.py` file. -Then add the following field at the top of the page (where ``12345`` is the ID of the Discourse topic):: - - :discourse: 12345 - -Manual-page links -^^^^^^^^^^^^^^^^^ - -When mentioning command line utilities, you may wish to link to the -corresponding manual page for the command. Ensure that the ``manpages_url`` -setting in your :file:`conf.py` is set appropriately and use the ``:manpage:`` -inline role within your text to create a link. - -For example, to link to man pages from the 24.04 LTS (Noble Numbat) release, -include the following in your :file:`conf.py`: - -.. code-block:: python - - manpages_url = "https://manpages.ubuntu.com/manpages/noble/en/man{section}/{page}.{section}.html" - -Then within your documentation, use the following reST: - -.. code-block:: rst - - You can use the :manpage:`dd(1)` utility to write the disk image to your - SD card. If the image is compressed, use :manpage:`aunpack(1)` to extract - it first. - - -YouTube links -^^^^^^^^^^^^^ - -To add a link to a YouTube video, use the following directive: - -.. list-table:: - :header-rows: 1 - - * - Input - - Output - * - .. code:: - - .. youtube:: https://www.youtube.com/watch?v=iMLiK1fX4I0 - :title: Demo - - - .. youtube:: https://www.youtube.com/watch?v=iMLiK1fX4I0 - :title: Demo - -The video title is extracted automatically and displayed when hovering over the link. -To override the title, add the ``:title:`` option. - -Internal references -~~~~~~~~~~~~~~~~~~~ - -You can reference pages and targets in this documentation set, and also in other documentation sets using Intersphinx. - -.. _a_section_target: - -Referencing a section -^^^^^^^^^^^^^^^^^^^^^ - -To reference a section within the documentation (either on the same page or on another page), add a target to that section and reference that target. - -.. _a_random_target: - -You can add targets at any place in the documentation. However, if there is no heading or title for the targeted element, you must specify a link text. - -.. list-table:: - :header-rows: 1 - - * - Input - - Output - - Description - * - ``.. _target_ID:`` - - - - Adds the target ``target_ID``. - - .. note:: - When defining the target, you must prefix it with an underscore. Do not use the starting underscore when referencing the target. - * - ``:ref:`a_section_target``` - - :ref:`a_section_target` - - References a target that has a title. - * - ``:ref:`Provided link text ``` - - :ref:`Provided link text ` - - References a target and specifies a title. - * - ``:external+project_key:ref:`an_external_target``` - - Default link text - - You can also reference targets in other Sphinx projects. ``project-key`` must be a key in the ``intersphinx_mapping`` dictionary in ``conf.py``. The link text defaults to the target's title. - -Adhere to the following conventions: - -- Never use external links to reference a section in the same doc set or a doc set that is linked with Intersphinx. It would likely cause a broken link in the future. -- Override the link text only when it is necessary. If you can use the referenced title as link text, do so, because the text will then update automatically if the title changes. -- Never "override" the link text with the same text that would be generated automatically. - -Referencing a page -^^^^^^^^^^^^^^^^^^ - -If a documentation page does not have a target, you can still reference it by using the ``:doc:`` role with the file name and path. - -.. list-table:: - :header-rows: 1 - :widths: 8 2 - - * - Input - - Output - * - ``:doc:`index``` - - :doc:`index` - * - ``:doc:`Provided link text ``` - - :doc:`Provided link text ` - * - ``:external+project_key:doc:`howto/index``` - - Default link text (from document title) - * - ``:external+project_key:doc:`Provided link text ``` - - Provided link text - -Adhere to the following conventions: - -- Only use the ``:doc:`` role when you cannot use the ``:ref:`` role, thus only if there is no target at the top of the file and you cannot add it. When using the ``:doc:`` role, your reference will break when a file is renamed or moved. -- Override the link text only when it is necessary. If you can use the document title as link text, do so, because the text will then update automatically if the title changes. -- Never "override" the link text with the same text that would be generated automatically. -- When using an external target, ``project_key`` must be a key in the ``intersphinx_mapping`` dictionary in ``conf.py``. - -Navigation ----------- - -Every documentation page must be included as a sub-page to another page in the navigation. - -This is achieved with the `toctree`_ directive in the parent page:: - - .. toctree:: - :hidden: - - sub-page1 - sub-page2 - -If a page should not be included in the navigation, you can suppress the resulting build warning by putting ``:orphan:`` at the top of the file. -Use orphan pages sparingly and only if there is a clear reason for it. - -.. tip:: - Instead of hiding pages that you do not want to include in the documentation from the navigation, you can exclude them from being built. - This method will also prevent them from being found through the search. - - To exclude pages from the build, add them to the ``custom_excludes`` variable in the :file:`conf.py` file. - -Lists ------ - -.. list-table:: - :header-rows: 1 - - * - Input - - Output - * - .. code:: - - - Item 1 - - Item 2 - - Item 3 - - - Item 1 - - Item 2 - - Item 3 - * - .. code:: - - 1. Step 1 - #. Step 2 - #. Step 3 - - 1. Step 1 - #. Step 2 - #. Step 3 - * - .. code:: - - a. Step 1 - #. Step 2 - #. Step 3 - - a. Step 1 - #. Step 2 - #. Step 3 - -You can also nest lists: - -.. tab-set:: - - .. tab-item:: Input - - .. code:: - - 1. Step 1 - - - Item 1 - - * Sub-item - - Item 2 - - i. Sub-step 1 - #. Sub-step 2 - #. Step 2 - - a. Sub-step 1 - - - Item - #. Sub-step 2 - .. tab-item:: Output - - - - 1. Step 1 - - - Item 1 - - * Sub-item - - Item 2 - - i. Sub-step 1 - #. Sub-step 2 - #. Step 2 - - a. Sub-step 1 - - - Item - #. Sub-step 2 - - - -Adhere to the following conventions: - -- In numbered lists, number the first item and use ``#.`` for all subsequent items to generate the step numbers automatically. -- Use ``-`` for unordered lists. When using nested lists, you can use ``*`` for the nested level. - -Definition lists -~~~~~~~~~~~~~~~~ - -.. list-table:: - :header-rows: 1 - - * - Input - - Output - * - .. code:: - - Term 1: - Definition - Term 2: - Definition - - Term 1: - Definition - Term 2: - Definition - -.. _style-guide-tables: - -Tables ------- - -reST supports different markup for tables. Grid tables are most similar to tables in Markdown, but list tables are usually much easier to use. -See the `Sphinx documentation `_ for all table syntax alternatives. - -Both markups result in the following output: - -.. list-table:: - :header-rows: 1 - - * - Header 1 - - Header 2 - * - Cell 1 - - Second paragraph cell 1 - - Cell 2 - * - Cell 3 - - Cell 4 - -Grid tables -~~~~~~~~~~~ - -See `grid tables`_ for reference. - -.. code:: - - +----------------------+------------+ - | Header 1 | Header 2 | - +======================+============+ - | Cell 1 | Cell 2 | - | | | - | 2nd paragraph cell 1 | | - +----------------------+------------+ - | Cell 3 | Cell 4 | - +----------------------+------------+ - -List tables -~~~~~~~~~~~ - -See `list tables`_ for reference. - -.. code:: - - .. list-table:: - :header-rows: 1 - - * - Header 1 - - Header 2 - * - Cell 1 - - 2nd paragraph cell 1 - - Cell 2 - * - Cell 3 - - Cell 4 - -Data tables -~~~~~~~~~~~ - -If you have a small amount of CSV data, you can include the data in the doc source. - -For example: - -.. code-block:: rst - - .. csv-table:: - :header: "Animal", "Number of legs", "Size" - - "Worm", 0, "Small" - "Penguin", 2, "Medium" - "Horse", 4, "Large" - "Ant", 6, "Small" - "Octopus", 8, "Medium" - -If you have a large amount of CSV data, or the data is generated by an automated process, -you can include the data from a file. - -For example: - -.. code-block:: rst - - .. csv-table:: - :file: /reuse/animals.csv - :header-rows: 1 - -Both markups result in the following output: - -.. csv-table:: - :header: "Animal", "Number of legs", "Size" - - "Worm", 0, "Small" - "Penguin", 2, "Medium" - "Horse", 4, "Large" - "Ant", 6, "Small" - "Octopus", 8, "Medium" - -Customize the column widths, character encoding, and so on, as described in the -`csv-table reference `_. - -The starter pack can also render interactive tables. See: :ref:`interactive-tables`. - -Notes ------ - -.. list-table:: - :header-rows: 1 - - * - Input - - Output - * - .. code:: - - .. note:: - A note. - - .. note:: - A note. - * - .. code:: - - .. warning:: - This might damage your hardware! - - .. warning:: - This might damage your hardware! - -Adhere to the following conventions: - -- Use notes sparingly. -- Only use the following note types: ``note``, ``warning`` -- Only use a warning if there is a clear hazard of hardware damage or data loss. - -Images ------- - -.. list-table:: - :header-rows: 1 - - * - Input - - Output - * - ``.. image:: https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png`` - - .. image:: https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png - * - .. code:: - - .. figure:: https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png - :width: 100px - :alt: Alt text - - Figure caption - - .. figure:: https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png - :width: 100px - :alt: Alt text - - Figure caption - -Adhere to the following conventions: - -- For local pictures, start the path with :file:`/` (for example, :file:`/images/image.png`). -- Use ``PNG`` format for screenshots and ``SVG`` format for graphics. -- If producing multiple output formats, use ``*`` as the file extension to have - Sphinx select the best image format for the output -- See `Five golden rules for compliant alt text`_ for information about how to word the alt text. - -Reuse ------ - -A big advantage of reST in comparison to plain Markdown is that it allows to reuse content. - -Substitution -~~~~~~~~~~~~ - -To reuse sentences and entire paragraphs -that have little markup or special formatting, -define `substitutions`_ for them in two possible ways. - -**Globally**, in a file named :file:`reuse/substitutions.txt` -that is included in a custom ``rst_epilog`` directive -(see the `Sphinx documentation `_): - -.. code-block:: python - :caption: :spellexception:`conf.py` - - rst_epilog = """ - .. include:: reuse/substitutions.txt - """ - - -.. code-block:: rest - :caption: :spellexception:`reuse/substitutions.txt` - - .. |version_number| replace:: 0.1.0 - - .. |rest_text| replace:: *Multi-line* text - that uses basic **markup**. - - .. |site_link| replace:: Website link - .. _site_link: https://example.com - - -**Locally**, putting the same directives in any reST file: - -.. code-block:: rest - :caption: :spellexception:`index.rst` - - .. |version_number| replace:: 0.1.0 - - .. |rest_text| replace:: *Multi-line* text - that uses basic **markup**. - - .. And so on - - -.. note:: - - Mind that substitutions can't be redefined; - for instance, accidentally including a definition twice causes an error: - - .. code-block:: none - - ERROR: Duplicate substitution definition name: "rest_text". - - -The definitions from the above examples are rendered as follows: - -.. list-table:: - :header-rows: 1 - - * - Input - - Output - - * - ``|version_number|`` - - |version_number| - - * - ``|rest_text|`` - - |rest_text| - - * - ``|site_link|_`` - - |site_link|_ - - -.. tip:: - - Use substitution names that hint at the included content - (for example, ``note_not_supported`` instead of ``note_substitution``). - - -File inclusion -~~~~~~~~~~~~~~ - -To reuse longer sections or text with more advanced markup, you can put the content in a separate file and include the file or parts of the file in several locations. - -To select parts of the text in a file, use ``:start-after:`` and ``:end-before:`` if possible. You can combine those with ``:start-line:`` and ``:end-line:`` if required (if the same text occurs more than once). Using only ``:start-line:`` and ``:end-line:`` is error-prone though. - -You cannot put any targets into the content that is being reused (because references to this target would be ambiguous then). You can, however, put a target right before including the file. - -By combining file inclusion and substitutions defined directly in a file, you can even replace parts of the included text. - -.. list-table:: - :header-rows: 1 - - * - Input - - Output - * - .. code:: - - .. include:: index.rst - :start-after: Also see the following information: - :end-before: Contents - - .. include:: index.rst - :start-after: Also see the following information: - :end-before: Contents - -Adhere to the following conventions: - -- Files that only contain text that is reused somewhere else should be placed in the :file:`reuse` folder and end with the extension ``.txt`` to distinguish them from normal content files. -- To make sure inclusions don't break, consider adding comments (``.. some comment``) to the source file as markers for starting and ending. - -Tabs ----- - -The recommended way of creating tabs is to use the tabs that the `Sphinx design`_ extension provides. - -.. list-table:: - :header-rows: 1 - - * - Input - - Output - * - .. code:: - - .. tab-set:: - - .. tab-item:: Tab 1 - :sync: key1 - - Content Tab 1 - - .. tab-item:: Tab 2 - :sync: key2 - - Content Tab 2 - - .. tab-set:: - - .. tab-item:: Tab 1 - :sync: key1 - - Content Tab 1 - - .. tab-item:: Tab 2 - :sync: key2 - - Content Tab 2 - -Alternatively, you can use the `Sphinx tabs`_ extension, which is also enabled by default. This was previously recommended due to limitations in Sphinx Design that are now fixed. - -.. list-table:: - :header-rows: 1 - - * - Input - - Output - * - .. code:: - - .. tabs:: - - .. group-tab:: Tab 1 - - Content Tab 1 - - .. group-tab:: Tab 2 - - Content Tab 2 - - .. tabs:: - - .. group-tab:: Tab 1 - - Content Tab 1 - - .. group-tab:: Tab 2 - - Content Tab 2 - -Glossary --------- - -You can define glossary terms in any file. Ideally, all terms should be collected in one glossary file though, and they can then be referenced from any file. - -.. list-table:: - :header-rows: 1 - - * - Input - - Output - * - .. code:: - - .. glossary:: - - an example term - Definition of an example term. - - .. glossary:: - - an example term - Definition of an example term. - * - ``:term:`an example term``` - - :term:`an example term` - -.. _section_more_useful_markup: - -More useful markup ------------------- - -.. list-table:: - :header-rows: 1 - - * - Input - - Output - - Description - * - .. code:: - - .. versionadded:: X.Y - - .. versionadded:: X.Y - - Can be used to distinguish between different versions. - * - .. code:: - - | Line 1 - | Line 2 - | Line 3 - - | Line 1 - | Line 2 - | Line 3 - - Line breaks that are not paragraphs. Use this sparingly. - * - .. code:: - - ---- - - A horizontal line - - Can be used to visually divide sections on a page. - * - ``.. This is a comment`` - - .. This is a comment - - Not visible in the output. - * - ``:abbr:`API (Application Programming Interface)``` - - :abbr:`API (Application Programming Interface)` - - Hover to display the full term. - * - ``:spellexception:`PurposelyWrong``` - - :spellexception:`PurposelyWrong` - - Explicitly exempt a term from the spelling check. - -.. LINKS - -.. _substitutions: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions -.. _rst_epilog: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-rst_epilog diff --git a/docs/release-notes/1.4.rst b/docs/release-notes/1.4.rst deleted file mode 100644 index d7f0f130..00000000 --- a/docs/release-notes/1.4.rst +++ /dev/null @@ -1,86 +0,0 @@ -.. meta:: - :description: The new features, changes, and fixes in Canonical's Sphinx Starter Pack 1.4.0. - - -.. _release-1.4: - -Canonical's Sphinx Starter Pack 1.4 -=================================== - -28 January 2026 - -These release notes cover new features and changes in Canonical's Sphinx Starter Pack -1.4.0. The `full commit log -`__ is -available on GitHub. - - -What's new in 1.4.0 -------------------- - - -Bridging the build -~~~~~~~~~~~~~~~~~~ - -The docs build and its Make targets are hosted in the ``docs`` directory. If the docs -are in a larger project with its own build system, it can be difficult to maintain and -run the two separate builds. - -We've taken some initial steps to make the docs build easier to integrate into larger -projects. With 1.4.0, the docs ``Makefile`` is now properly callable by a parent build -system, because the main build can ensure the ``VENVDIR``, ``BUILDDIR``, and ``VALEDIR`` -variables are set to the right locations in the project. - -The new guide :ref:`bridge-project-and-docs-builds` covers in detail how to integrate the -docs build in a parent Python project. - - -Build explanation -~~~~~~~~~~~~~~~~~ - -We've released an :ref:`explanation of the starter pack build ` to -share with you some of its design and inner workings. - - -Removed in 1.4.0 ----------------- - - -Metrics check -~~~~~~~~~~~~~ - -The metrics check was a set of scripts called with ``make allmetrics`` that collected -measures and statistics about source documents and rendered HTML files. - -We've removed this check because it was underused and underdeveloped. There have been no -reported usages of it from any active projects at Canonical. - - -Fixed bugs and issues ---------------------- - -1.4.0 -~~~~~ - -- `#496 `__ myst-parser - causes Python dependency check to time out -- `#509 `__ Markdown - linter falsely flags contents of ``.sphinx`` dir - - -1.4.1 -~~~~~ - -- `#444 `__ Patch the - ``version`` file so the upgrade script works - - -Contributors ------------- - -We would like to express a big thank you to all the people who contributed to this -release: - -:literalref:`medubelko `, -:literalref:`minaelee `, and -:literalref:`tang-mm ` diff --git a/docs/release-notes/1.5.rst b/docs/release-notes/1.5.rst deleted file mode 100644 index 45bf075d..00000000 --- a/docs/release-notes/1.5.rst +++ /dev/null @@ -1,176 +0,0 @@ -.. meta:: - :description: The new features, changes, and fixes in Canonical's Sphinx Starter Pack 1.5. - - -.. _release-1.5: - -Canonical's Sphinx Starter Pack 1.5 -=================================== - -26 February 2026 - -These release notes cover new features and changes in Canonical's Sphinx Starter Pack -1.5. The `full commit log -`__ is available -on GitHub. - -Bring these changes into your docs: - -- :ref:`Update starter pack 1.3.0 and higher ` -- :ref:`Update starter pack 1.2.0 and lower ` - - -What's new in 1.5 ------------------ - - -New versioning -~~~~~~~~~~~~~~ - -We've revised our approach to versions. Because the starter pack is an evergreen -repository and not packaged software, it requires a different version process and -scheme. - -Starting with 1.5, the starter pack only provides major and minor version numbers. Patch -numbers now correspond to the Git commits in the repository's ``main`` branch between -tagged releases. - -.. image:: assets/release-commit-history.svg - :alt: A mock linear Git commit history of the main branch, with nodes for tagged minor versions and intermediate untagged commits. - :width: 75% - -Going forward, we'll continue to tag major and minor releases, and distribute hotfixes -to the tip of the repository's history. If untagged patch versions are too risky, or -your software policy requires that you lock to a specific version, we recommend you pin -to the latest minor version. - - -New upgrade guide -~~~~~~~~~~~~~~~~~ - -For docs based on starter pack 1.3 or higher, we published -:ref:`update-new-starter-pack`. - - -Contribution guide -~~~~~~~~~~~~~~~~~~ - -We've added a contribution guide for the project in ``CONTRIBUTING.md``. It's available -in upgraded repositories and `on GitHub -`__. - -This guide is for developers of the starter pack. It's not meant for your project. After -updating, remove it from your project. - - -Quiet link check -~~~~~~~~~~~~~~~~ - -The link check by default was too verbose, logging every checked link. - -The check now only logs on errors. - - -Environment variable updates -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -For docs embedded into larger projects, the Make commands might be called in the -project's main build system. Because docs builds used common names like ``BUILDDIR``, it -was possible that they could conflict with variables set by the parent build system -meant for other software. - -We made all the docs variables conditional, so you can set them ahead of time in the -parent build system. - -To mediate the risk of conflicts, we overhauled the variable names, adding a prefix and -splitting along common word boundaries. - -.. list-table:: - :header-rows: 1 - :widths: 1 3 - - * - Old variable name - - New variable name - * - ``VENVDIR`` - - ``DOCS_VENVDIR`` - * - ``VENV`` - - ``DOCS_VENV`` - * - ``SOURCEDIR`` - - ``DOCS_SOURCEDIR`` - * - ``REQPDFPACKAGES`` - - ``DOCS_PDFPACKAGES`` - * - ``VOCAB_CANONICAL`` - - ``DOCS_VOCAB`` - * - ``SPHINXDIR`` - - ``SPHINX_DIR`` - * - ``SPHINXBUILD`` - - ``SPHINX_BUILD`` - * - ``VALEDIR`` - - ``VALE_DIR`` - * - ``VALECONFIG`` - - ``VALE_CONFIG`` - * - ``TARGET`` - - ``CHECK_PATH`` - - -Dependency changes in 1.5 -------------------------- - -.. list-table:: - :header-rows: 1 - :widths: 2 1 1 - - * - Package - - From - - To - * - canonical-sphinx - - >=0.5.1 - - ~=0.6 - * - sphinx-related-links - - >=0.1.1 - - >=0.1.2 - - -Removed in 1.5 --------------- - - -``wokeignore`` directive -~~~~~~~~~~~~~~~~~~~~~~~~ - -The ``wokeignore`` directive is removed because it was redundant. Use the -:literalref:`vale-ignore ` role -instead. - - -Contribution guide template -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -We removed a contribution guide template that was placed in the documentation in error. - - -Fixed in 1.5 ------------- - -- `#472 `__ invalid - characters in Makefile cause infinite loop -- `#477 `__ Version slug - is duplicated in sitemaps -- `#501 `__ - Example-product docs are used in links but no longer available -- `#514 `__ Workflows - can be called by other projects - - -Contributors ------------- - -We would like to express a big thank you to all the people who contributed to this release: - -:literalref:`a-velasco `, -:literalref:`akcano `, -:literalref:`jahn-junior `, -:literalref:`medubelko `, -:literalref:`minaelee `, -:literalref:`nhennigan `, and -:literalref:`odadacharles ` diff --git a/docs/release-notes/1.6.rst b/docs/release-notes/1.6.rst deleted file mode 100644 index 52feaad8..00000000 --- a/docs/release-notes/1.6.rst +++ /dev/null @@ -1,133 +0,0 @@ -.. meta:: - :description: The new features, changes, and fixes in Canonical's Sphinx Starter Pack 1.6. - - -.. _release-1.6: - -Canonical's Sphinx Starter Pack 1.6 -=================================== - -24 March 2026 - -These release notes cover new features and changes in Canonical's Sphinx Starter Pack -1.6. The `full commit log -`__ is available -on GitHub. - -Bring these changes into your docs: - -- :ref:`Update starter pack 1.3.0 and higher ` -- :ref:`Update starter pack 1.2.0 and lower ` - - -What's new in 1.6 ------------------ - - -New extension for redirects -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If your project has a lot of redirects, they can begin to clutter your build -configuration file. To remedy this, we changed the default extension for redirects to -sphinx-rerediraffe, a fork of sphinxext-rediraffe that supports external redirects and -cleans up destination URLs. - -In your docs, you can now list redirects in a ``redirects.txt`` file and configure your -project to use them with: - -.. code-block:: diff - :caption: conf.py - :class: no-copybutton - - - redirects = { - - "source-path": "destination-path" - - } - + rediraffe_redirects = "redirects.txt" - + rediraffe_dir_only = True - -If your project uses relative redirects, these should be rewritten relative to the -root of the docs directory. - -For example, if you were previously redirecting ``/how-to/set-up/project/`` to -``../set-up-project/``, the redirect should now read: - -.. code-block:: text - :caption: redirects.txt - :class: no-copybutton - - "/how-to/set-up/project/" "/how-to/set-up-project/" - - -Remote cookie banner files -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Following the recent changes to the cookie banner, we evaluated how its files are -distributed and maintained. In version 1.6, these files are hosted centrally so you -don't need to duplicate them to enable Google Analytics for your project. - -If you've already enabled Google Analytics in your project, you should make it a -priority to use the centrally-hosted files, as they contain important legal changes. For -guidance, refer to :ref:`how-to-enable-google-analytics`. - - -Virtual environment path -~~~~~~~~~~~~~~~~~~~~~~~~ - -To make the Python virtual environment more discoverable, we moved it from -``docs/.sphinx/venv`` to ``docs/.venv``. This also preserves the ``.sphinx/`` -directory's scope, which is to house static utility files. - -Once you've replaced all occurrences of the old path, remove the old virtual -environment. - - -Ulwazi testing guide -~~~~~~~~~~~~~~~~~~~~ - -Our new Sphinx theme based on the Vanilla framework, Ulwazi, is now available for -testing. To try it out, follow the new guide, :ref:`how-to-test-ulwazi-theme`. - - -Starter Pack explanation -~~~~~~~~~~~~~~~~~~~~~~~~ - -We published :ref:`explanation-structure` to explain the functionality of and -relationships between the core elements of the Starter Pack. - - -Deprecated features -------------------- - -The following features are deprecated and will be removed in an upcoming version of -the Starter Pack. - - -sphinx-reredirects -~~~~~~~~~~~~~~~~~~ - -The sphinx-reredirects extension is deprecated in 1.6. Redirects, both internal and -external, should now be handled with sphinx-rerediraffe. - - -Fixed for 1.6 -------------- - -- `#535 `__ Markdown - checks are incompatible with default runner version -- `#550 `__ Makefile - doesn't allow for :vale-ignore:`pymarkdownlnt` to exit with a status code of 1 - - -Contributors ------------- - -We would like to express a big thank you to all the people who contributed to this -release: - -:literalref:`akcano `, -:literalref:`AnneCYH `, -:literalref:`arturo-seijas `, -:literalref:`jahn-junior `, -:literalref:`odadacharles `, -:literalref:`wctaylor `, and -:literalref:`yhontyk ` diff --git a/docs/release-notes/assets/release-commit-history.svg b/docs/release-notes/assets/release-commit-history.svg deleted file mode 100644 index 436ceacb..00000000 --- a/docs/release-notes/assets/release-commit-history.svg +++ /dev/null @@ -1 +0,0 @@ -main0-e0d6fea1-ed443e82-ffbd8421.53-68e10564-f62b1a15-89c03b21.66-4dfdc497-7e634e7 \ No newline at end of file diff --git a/docs/release-notes/index.rst b/docs/release-notes/index.rst index 71c070ae..ed195fbd 100644 --- a/docs/release-notes/index.rst +++ b/docs/release-notes/index.rst @@ -2,48 +2,3 @@ Release notes ============= - -This page lists the notes for past releases of Canonical's Sphinx Starter Pack, which -summarize new features, bug fixes and breaking changes in each version. It also contains -the release and support policies for the starter pack. - - -Latest release --------------- - -- :ref:`release-1.6` - - -Past releases -------------- - -- :ref:`release-1.5` -- :ref:`release-1.4` - - -Release versioning ------------------- - -Starter pack version naming follows the Semantic Versioning 2.0.0 scheme with -modifications. It has numbers for major and minor version, but *not* patch versions. - -.. list-table:: - :header-rows: 1 - - * - Version - - Example - - Signifies - * - Major - - **1**.3 - - Improvements that aren't backward-compatible. - * - Minor - - 1.\ **3** - - New or improved features that are simple to adopt and backward-compatible. - - -.. toctree:: - :hidden: - - 1.6 <1.6> - 1.5 <1.5> - 1.4 <1.4> diff --git a/docs/set-up-a-new-project.rst b/docs/set-up-a-new-project.rst deleted file mode 100644 index 159e7cf6..00000000 --- a/docs/set-up-a-new-project.rst +++ /dev/null @@ -1,139 +0,0 @@ -.. _set-up-a-new-project: - -=================================== -Set up a new project -=================================== - -This page contains a short guide on how to set up and use the starter pack. - -.. _initial-setup: - -Copy the starter pack -===================== - -If you're starting a new project, `copy the starter pack as a template repository `__. - -If you're creating documentation for a Canonical project, set the owner to **canonical**. - -If you're adding documentation to an existing software project, copy the following files from the starter pack repository into your project: - -* the entire :file:`docs` directory -* :file:`.readthedocs.yaml` (configuration for the building on Read the Docs) -* the entire :file:`.github/workflows` directory - - -.. _remove-unneeded-files: - -Remove the unneeded files -========================= - -Next, review the starter pack files and remove those that could interfere with your project. - -Remove the files that can't be reused: - -- :file:`CONTRIBUTING.md` -- :file:`.github/CODEOWNERS` -- :file:`.github/workflows/test-starter-pack.yml` - -Review and remove the GitHub workflows in ``.github/workflows/`` that your project might not need: - -- :file:`cla-check.yml` verifies whether contributors have signed the `Canonical License Agreement `_. All Canonical projects require this check, so if you're adding docs to an existing Canonical project that already has it, remove this workflow. -- :file:`sphinx-python-dependency-build-checks.yml` verifies Python dependencies for the documentation system. If your project has its own dependency checks, remove this workflow. -- :file:`markdown-style-checks.yml` runs the built-in Markdown linter. If your project already validates its Markdown files, remove this workflow. - - -Build and run the local server -============================== - -Building the documentation requires ``make``, ``python3``, ``python3-venv``, ``python3-pip``. - -In :file:`docs`, run:: - - make run - -This creates and activates a virtual environment in :file:`docs/.venv`, builds the documentation and serves it at :literalref:`http://127.0.0.1:8000/`. - -The server watches the source files, including :file:`docs/conf.py`, and rebuilds automatically on changes. - - -Edit content -============== - -Now that you've verified you can build and run the sample starter pack documentation, you can replace it with your own content. - -The landing page is :file:`docs/index.rst`. Other pages are under one of the sub-directories under :file:`docs/`. - -The navigation menu structure is set by ``.. toctree::`` directives. These directives define the hierarchy of included content throughout the documentation. -The :file:`index.rst` page's ``toctree`` block contains the top level navigation, which by default is the `Diátaxis`_ documentation structure. - -To add a new page to the documentation: - -1. Create a new file in the `docs/` folder. For example, to create a new **Reference** page, create a document under `docs/reference/` directory called :file:`settings.rst`, insert the following |RST|-formatted heading ``Settings`` at the beginning, and then save the file: - - .. code-block:: rest - :caption: reStructuredText title example - - Settings - ======== - - If you prefer to use Markdown (MyST) syntax instead of |RST|, you can create a Markdown file. For example, :file:`settings.md` file with the following Markdown-formatted heading at the beginning: - - .. code-block:: markdown - :caption: Markdown title example - - # Settings - -2. Add the new page to the Navigation Menu: open the :file:`docs/reference/index.rst` file or another file where you want to nest the new page; at the bottom of the file, locate the ``toctree`` directive and add a properly indented line containing the relative path (without a file extension) to the new file created in the first step. For example, ``settings``. - - The ``toctree`` block will now look like this: - - .. code-block:: rest - - .. toctree:: - :hidden: - :maxdepth: 2 - - Documentation checks - style-guide - style-guide-myst - settings - -The documentation will now show the new page added to the navigation when rebuilt. - -By default, the page's title (the first heading in the file) is used for the Navigation Menu entry. You can overwrite a name of a Menu element by specifying it explicitly in the ``toctree`` block, for example: ``Reference     ``. - - -Configure settings -================== - -Work through the settings in :file:`docs/conf.py`. Most parameters can be left with the default values as they can be changed later. :ref:`configure-your-project` contains further guidance. - - -Pre-commit hooks (optional) -=========================== - -Use `pre-commit `_ hooks with the starter pack -to automate checks like spelling and inclusive language. - -The starter pack includes a ready-to-use :file:`.pre-commit-config.yaml` file -under :file:`docs/.sphinx/`: - -.. literalinclude:: /.sphinx/.pre-commit-config.yaml - :language: yaml - -For a new project, copy this file to your project's root directory; -for an existing project using ``pre-commit``, -add these hooks to your configuration. - -To apply the configuration, install the starter pack hooks, for instance:: - - pre-commit install --config docs/.sphinx/.pre-commit-config.yaml - - -After that, you should see the checks running with every commit:: - - git commit -m 'add spelling errors' - - Run make spelling.......................................................Failed - Run make linkcheck......................................................Passed - Run make woke...........................................................Passed diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst new file mode 100644 index 00000000..48020555 --- /dev/null +++ b/docs/tutorials/index.rst @@ -0,0 +1,4 @@ +.. _tutorials: + +Tutorials +========= From 972941cbff572e658529c995d30a1acf8df435db Mon Sep 17 00:00:00 2001 From: jahn-junior Date: Tue, 21 Apr 2026 15:36:18 -0700 Subject: [PATCH 02/10] chore: remove more whitespace --- docs/conf.py | 19 ++----------------- 1 file changed, 2 insertions(+), 17 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 9766104a..1d3f0b2a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -14,7 +14,6 @@ # all documentation consistent and on brand: # https://github.com/canonical/canonical-sphinx - ####################### # Project information # ####################### @@ -37,25 +36,21 @@ # Documentation website URL ogp_site_url = os.environ.get("READTHEDOCS_CANONICAL_URL", "/") - # Preview name of the documentation website # # TODO: To use a different name for the project in previews, update the next line. ogp_site_name = project - # Preview image URL # # TODO: To customise the preview image, update the next line. ogp_image = "https://assets.ubuntu.com/v1/cc828679-docs_illustration.svg" - # Product favicon # # TODO: To customise the favicon, uncomment and update the next line. # html_favicon = ".sphinx/_static/favicon.png" - # Dictionary of values to pass into the Sphinx context for all pages: # https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_context html_context = { @@ -171,7 +166,6 @@ # html_static_path = ["_static"] # templates_path = ["_templates"] - ############# # Redirects # ############# @@ -187,7 +181,6 @@ # Strips '/index.html' from destination URLs when building with 'dirhtml' rediraffe_dir_only = True - ########################### # Link checker exceptions # ########################### @@ -202,7 +195,6 @@ r"https://.*\.sourceforge\.(net|io)/.*", ] - # A regex list of URLs where anchors are ignored by 'make linkcheck' linkcheck_anchors_ignore_for_url = [r"https://github\.com/.*"] @@ -223,7 +215,6 @@ # # myst_enable_extensions = set() - # Custom Sphinx extensions; see # https://www.sphinx-doc.org/en/master/usage/extensions/index.html extensions = [ @@ -255,33 +246,27 @@ ".venv*", ] -# Adds custom CSS files, located under 'html_static_path' - +# Adds custom CSS files, located remotely or in 'html_static_path'. # html_css_files = [ # "https://assets.ubuntu.com/v1/d86746ef-cookie_banner.css", # ] - -# Adds custom JavaScript files, located under 'html_static_path' - +# Adds custom JavaScript files, located remotely or in 'html_static_path'. # html_js_files = [ # "https://assets.ubuntu.com/v1/287a5e8f-bundle.js", # ] - # Specifies a reST snippet to be appended to each .rst file rst_epilog = """ .. include:: /reuse/links.txt .. include:: /reuse/substitutions.txt """ - # Feedback button at the top; enabled by default # # TODO: To disable the button, uncomment the next line. # disable_feedback_button = True - # Your manpage URL # # TODO: To enable manpage links, uncomment and replace {codename} with required From 53352a7f8dffb9f0a919d65984ccbfdfb1ff997b Mon Sep 17 00:00:00 2001 From: jahn-junior Date: Wed, 29 Apr 2026 18:30:41 -0700 Subject: [PATCH 03/10] docs: update README --- ...starter-pack.yml => test-sphinx-stack.yml} | 8 +-- README.md | 70 +++++++++++++------ 2 files changed, 51 insertions(+), 27 deletions(-) rename .github/workflows/{test-starter-pack.yml => test-sphinx-stack.yml} (85%) diff --git a/.github/workflows/test-starter-pack.yml b/.github/workflows/test-sphinx-stack.yml similarity index 85% rename from .github/workflows/test-starter-pack.yml rename to .github/workflows/test-sphinx-stack.yml index e50e4d8f..bfbf5036 100644 --- a/.github/workflows/test-starter-pack.yml +++ b/.github/workflows/test-sphinx-stack.yml @@ -1,7 +1,7 @@ -# This workflow tests the starter pack. -# Don't run this workflow on any repos that use the starter pack. +# This workflow tests the Sphinx Stack. +# Don't run this workflow on any repos that use the Sphinx Stack. -name: Test starter pack +name: Test Sphinx Stack on: push: @@ -10,7 +10,7 @@ on: jobs: test-docs: - name: Test on docs folder + name: Test on docs directory runs-on: ubuntu-latest steps: - name: Check out repo diff --git a/README.md b/README.md index e74fa995..a47e5c7b 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,65 @@ -# Canonical's Sphinx Starter Pack +# Sphinx Stack -*A pre-configured repository to build and publish documentation with Sphinx.* +[![Sphinx Stack test](https://github.com/canonical/sphinx-stack/actions/workflows/test-sphinx-stack.yml/badge.svg)](https://github.com/canonical/sphinx-stack/actions/workflows/test-sphinx-stack.yml) -## Description +A standard set of tools for building and publishing Sphinx documentation. -The Documentation starter pack includes: +The Sphinx Stack contains a set of CLI commands and a default set of extensions, +configuration options, and tests. -* A bundled [Sphinx] theme, configuration, and extensions -* Support for both reStructuredText (reST) and MyST Markdown -* Build checks for links, spelling, and inclusive language -* Customisation support layered over a core configuration +## Basic usage -See the full documentation: https://canonical-starter-pack.readthedocs-hosted.com/ +To try out the Sphinx Stack, clone it locally and navigate to the `/docs` directory: -## Structure +```shell +git clone git@github.com:canonical/sphinx-stack.git +cd docs +``` -This section outlines the structure of this repository, and some key files. +Then, run the command -### `docs/` +```shell +make run +``` -This directory contains the documentation for the starter pack itself. +This will create a Python virtual environment, install necessary dependencies, build the +documentation, and serve it in a local webserver. -To view it in your browser, navigate to this directory and type `make run`. +You can access it in your browser at http://127.0.0.1:8000. -### `.github/workflows/` +To learn more about how to install and configure the Sphinx Stack for your own project, +see the [Set up a new +project](https://canonical-sphinx-stack.readthedocs-hosted.com/stable/tutorial/set-up/) +guide in the official documentation. -This directory contains files used for documentation build checks via GitHub's CI. +## Requirements and limitations -The file `test-starter-pack.yml` tests the functionality of the starter pack project. +The Sphinx Stack is designed for projects hosted on GitHub. This is necessary to run the +automatic checks in .github/workflows, and to publish your documentation on Read the +Docs. -## Contributing +If you have a project that is hosted on a different versioning platform, like Launchpad, +[reach out to us](#reach-out). -We welcome contributions to this project! If you have suggestions, bug fixes, or improvements, please open an issue or submit a pull request. +## Community and support -Please read and sign our [Contributor Licence Agreement (CLA)] before submitting any changes. The agreement grants Canonical permission to use your contributions. The author of a change remains the copyright owner of their code (no copyright assignment occurs). +The Sphinx Stack is an open-source project that warmly welcomes community involvement. - +If you’re new to the community, make sure to read through the [Ubuntu Code of +Conduct](https://ubuntu.com/community/code-of-conduct) first. -[Sphinx]: https://www.sphinx-doc.org/ -[Contributor Licence Agreement (CLA)]: https://ubuntu.com/legal/contributors +### Reach out + +* Report an issue or make a suggestion via + [GitHub](https://github.com/canonical/sphinx-stack/issues) +* Come chat with the Canonical Documentation team in our [public Matrix + channel](https://matrix.to/#/#documentation:ubuntu.com) + +### Contribute + +The Sphinx Stack provides a shared foundation for Sphinx documentation projects, and +contributions help improve the documentation of all its users. + +* See [CONTRIBUTING.md](CONTRIBUTING.md) for more details on contributing to + development or documentation. +* Check [open issues](https://github.com/canonical/sphinx-stack/issues) From 8794dc7f0a0afd4ee58d02d5a5508e2cac76bbb6 Mon Sep 17 00:00:00 2001 From: jahn-junior Date: Wed, 29 Apr 2026 18:42:44 -0700 Subject: [PATCH 04/10] docs: update CONTRIBUTING --- CONTRIBUTING.md | 194 ++++++++++++++++++++++++++++++------------------ 1 file changed, 123 insertions(+), 71 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a17d8e28..11de6792 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,15 +1,23 @@ -# Contributing to the Starter Pack +# Contributing to Sphinx Stack development -The Starter Pack provides a shared foundation for Sphinx documentation projects, and contributions help improve the documentation of all its users. The Documentation Practice team performs most of the work, but all contributors are welcome. +The Sphinx Stack is a shared foundation for Sphinx documentation projects, and +contributions help improve the documentation of all its users. The Documentation +Practice team performs most of the work, but all contributors are welcome. Common contributions include: - Bug fixes: Build errors, broken links, configuration issues -- Documentation: How-to guides on Starter Pack features and usage, syntax references, troubleshooting information -- Improvements: Better defaults, new extensions, workflow enhancements, new or improved style rules +- Improvements: Better defaults, new extensions, workflow enhancements, new or improved + style rules - Dependency updates: Security patches, compatibility fixes, better tooling -If you run into any problems or see room for improvement, we encourage you to open an issue or even contribute a fix. +If you run into any problems or see room for improvement, we encourage you to open an +issue or even contribute a fix. + +> This guide only covers contributions to development. If you're interested in +> contributing to the Sphinx Stack documentation, refer to the [documentation +> repository's +> guide](https://github.com/canonical/sphinx-stack-docs/blob/main/CONTRIBUTING.md). ## Review the project expectations @@ -17,62 +25,78 @@ Review these three documents before contributing: ### Ubuntu Code of Conduct -When contributing, you must abide by the [Ubuntu Code of Conduct](https://ubuntu.com/community/ethos/code-of-conduct). Projects governed by Canonical expect good conduct and excellence from every member. +When contributing, you must abide by the [Ubuntu Code of +Conduct](https://ubuntu.com/community/ethos/code-of-conduct). Projects governed by +Canonical expect good conduct and excellence from every member. ### Canonical Contributor License Agreement -Code contributions can only be accepted from contributors who have signed our [Contributor License Agreement (CLA)](https://ubuntu.com/legal/contributors). Signing the agreement grants Canonical permission to use your contributions, and you remain the copyright owner of your work (no copyright assignment occurs). +Code contributions can only be accepted from contributors who have signed our +[Contributor License Agreement (CLA)](https://ubuntu.com/legal/contributors). Signing +the agreement grants Canonical permission to use your contributions, and you remain the +copyright owner of your work (no copyright assignment occurs). -Review the terms of the agreement before signing it or committing anything. If you agree and choose to sign it, your work can be incorporated into the repository. +Review the terms of the agreement before signing it or committing anything. If you agree +and choose to sign it, your work can be incorporated into the repository. ### Open source license -The Starter Pack is licensed under [GPL-3.0](LICENSE). Documentation for this project is licensed under CC-BY-SA 3.0. +The Sphinx Stack is licensed under [GPL-3.0](LICENSE). ## Report an issue or open a request -If you find a bug or feature gap in the Starter Pack, look for it in the [project's GitHub issues](https://github.com/canonical/sphinx-docs-starter-pack/issues) first. Add your voice to the thread if you have fresh input. +If you find a bug or feature gap in the Sphinx Stack, look for it in the [project's +GitHub issues](https://github.com/canonical/sphinx-stack/issues) first. Add +your voice to the thread if you have fresh input. -If the bug or feature doesn't have an issue, [open one](https://github.com/canonical/sphinx-docs-starter-pack/issues/new/choose). +If the bug or feature doesn't have an issue, [open +one](https://github.com/canonical/sphinx-stack/issues/new/choose). -## What belongs in the Starter Pack +## What belongs in the Sphinx Stack -The Starter Pack is designed to be a minimal, flexible foundation for diverse documentation projects. +The Sphinx Stack is designed to be a minimal, flexible foundation for diverse +documentation projects. -**Belongs in the Starter Pack:** +**Belongs in the Sphinx Stack:** - Bug fixes for core functionality - Improvements to default configuration that benefit all users -- Documentation about existing features - Dependency updates for security or compatibility -**May not belong in the Starter Pack:** -- Optional tooling or features (these should be opt-in and implemented by projects using the Starter Pack) -- Opinionated formatting or linting rules that would cause a sizable portion of existing doc sets to fail checks suddenly +**May not belong in the Sphinx Stack:** +- Optional tooling or features (these should be opt-in and implemented by projects using + the Sphinx Stack) +- Opinionated formatting or linting rules that would cause a sizable portion of existing + doc sets to fail checks suddenly - Changes that conflict with existing workflows - Features that are project-specific rather than general-purpose -- UI-related changes may be better suited for the ongoing alternative theme update project (ask maintainers) +- UI-related changes may be better suited for the ongoing alternative theme update + project (ask maintainers) -When in doubt, open an issue first to discuss whether the change aligns with the project's goals. +When in doubt, open an issue first to discuss whether the change aligns with the +project's goals. ## Development setup -Create a [personal fork](https://github.com/canonical/sphinx-docs-starter-pack/fork) of the repository, then clone it and add the upstream remote: +Create a [personal fork](https://github.com/canonical/sphinx-stack/fork) of +the repository, then clone it and add the upstream remote: -With [SSH](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account): +With +[SSH](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account): ```bash -git clone git@github.com:/sphinx-docs-starter-pack -cd sphinx-docs-starter-pack -git remote add upstream git@github.com:canonical/sphinx-docs-starter-pack +git clone git@github.com:/sphinx-stack +cd sphinx-stack +git remote add upstream git@github.com:canonical/sphinx-stack git fetch upstream ``` -With [HTTPS](https://docs.github.com/en/get-started/git-basics/about-remote-repositories#cloning-with-https-urls): +With +[HTTPS](https://docs.github.com/en/get-started/git-basics/about-remote-repositories#cloning-with-https-urls): ```bash -git clone https://github.com//sphinx-docs-starter-pack -cd sphinx-docs-starter-pack -git remote add upstream https://github.com/canonical/sphinx-docs-starter-pack +git clone https://github.com//sphinx-stack +cd sphinx-stack +git remote add upstream https://github.com/canonical/sphinx-stack git fetch upstream ``` @@ -88,15 +112,21 @@ make html ### Research the topic -All significant work should be tied to an existing issue. Before starting, comment on the issue to have it assigned to you. +All significant work should be tied to an existing issue. Before starting, comment on +the issue to have it assigned to you. #### Minor changes -Check [GitHub issues](https://github.com/canonical/sphinx-docs-starter-pack/issues) for existing reports. If none exist, [open one](https://github.com/canonical/sphinx-docs-starter-pack/issues/new/choose) and state your interest in working on it. +Check [GitHub issues](https://github.com/canonical/sphinx-stack/issues) for +existing reports. If none exist, [open +one](https://github.com/canonical/sphinx-stack/issues/new/choose) and state +your interest in working on it. #### Major changes -Describe your proposal in the issue thread, including the plan, tests, and documentation. For new documentation pages, propose a [Diátaxis](https://diataxis.fr) category. +Describe your proposal in the issue thread, including the plan, tests, and +documentation. For new documentation pages, propose a [Diátaxis](https://diataxis.fr) +category. ### Create a development branch @@ -107,15 +137,16 @@ git fetch upstream git checkout -b ``` -Name your branch `-` (e.g., `issue-235-add-string-sanitizer`), keeping it under 80 characters. +Name your branch `-` (e.g., `issue-235-add-string-sanitizer`), +keeping it under 80 characters. ### Make your changes Follow these guidelines: - Use separate commits for each logical change, and for changes to different components -- Keep the Starter Pack minimal by default; optional features are best implemented - by the projects using the Starter Pack rather than the Starter Pack itself +- Keep the Sphinx Stack minimal by default; optional features are best implemented + by the projects using the Sphinx Stack rather than the Sphinx Stack itself ### Commit a change @@ -134,7 +165,8 @@ To determine the commit type, check the file history with `git log --oneline **Tip** > -> If you're unsure which type to use, the commit may be doing too much, so split it into smaller commits instead. Select the highest-ranked type that fits: +> If you're unsure which type to use, the commit may be doing too much, so split it into +> smaller commits instead. Select the highest-ranked type that fits: > > - `ci` > - `build` @@ -149,34 +181,47 @@ To determine the commit type, check the file history with `git log --oneline **Tip** > -> You can configure your Git client to sign commits by default for any local repository by running `git config --global commit.gpgsign true`. Once you have done this, you no longer need to add `-S` to your commits explicitly. +> You can configure your Git client to sign commits by default for any local repository +> by running `git config --global commit.gpgsign true`. Once you have done this, you no +> longer need to add `-S` to your commits explicitly. > > See [GitHub Docs - Signing commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits) for more information. -If you've made an unsigned commit and encounter the "Commits must have verified signatures" error when pushing your changes to the remote: +If you've made an unsigned commit and encounter the "Commits must have verified +signatures" error when pushing your changes to the remote: -1. Amend the most recent commit by signing it without changing the commit message, and push again: +1. Amend the most recent commit by signing it without changing the commit message, and + push again: ```bash git commit --amend --no-edit -n -S git push ``` -2. If you still encounter the same error, confirm that your GitHub account has been set up properly to sign commits as described in the [GitHub Docs - About commit signature verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification). +2. If you still encounter the same error, confirm that your GitHub account has been set + up properly to sign commits as described in the [GitHub Docs - About commit signature + verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification). > **Tip** > - > If you use SSH keys to sign your commits, make sure to add a "Signing Key" type in your GitHub account. See [GitHub Docs - Adding a new SSH key to your account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account) for more information. + > If you use SSH keys to sign your commits, make sure to add a "Signing Key" type in + > your GitHub account. See [GitHub Docs - Adding a new SSH key to your + > account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account) + > for more information. ### Test the change @@ -203,15 +248,18 @@ make run ### Document the change -This documentation uses [Diátaxis](https://diataxis.fr). For small changes, update existing how-to guides and references. For major changes or new flows, create new pages in the appropriate category. +This documentation is sourced from +[canonical/sphinx-stack-docs](https://github.com/canonical/sphinx-stack-docs) and uses +[Diátaxis](https://diataxis.fr). For small changes, update existing how-to guides and +references. For major changes or new flows, create new pages +in the appropriate category. -Run the same basic checks locally that GitHub runs on PRs; see [Test the change](#test-the-change). +Run the same basic checks locally that GitHub runs on PRs; see [Test the +change](#test-the-change). #### Changelog guidance -Doc-only changes generally do not require changelog entries. However, reviewers may request one for notable additions such as significant new how-to guides or reference documentation. - -For non-documentation changes, ensure that feature changes and fixes are documented in the relevant release notes. +Ensure that feature changes and fixes are documented in the relevant release notes. ### Push the branch and open a PR @@ -219,7 +267,8 @@ For non-documentation changes, ensure that feature changes and fixes are documen git push -u origin ``` -Next, open a PR on GitHub. Format its title as a conventional commit (GitHub may do this automatically for single-commit branches). +Next, open a PR on GitHub. Format its title as a conventional commit (GitHub may do this +automatically for single-commit branches). ### Describing PRs @@ -231,13 +280,13 @@ Your PR should include the following details: - Testing: How reviewers can verify the change or test the fix - Reversibility: For costly-to-reverse decisions, explain reasoning and reversal steps -Make sure to peek at the preview for documentation changes (find the `Read the Docs build` check and click `...` - `View details`). If your PR adds or changes specific documentation pages, include links to the preview pages in the PR description. - ## CI/CD pipeline -The repository configures multiple automated checks. Some are conditional based on target branch or changed files. +The repository configures multiple automated checks. Some are conditional based on +target branch or changed files. -If a check fails, review the logs for remediation guidance. For failures unrelated to your changes, rebase against the latest base branch. +If a check fails, review the logs for remediation guidance. For failures unrelated to +your changes, rebase against the latest base branch. ### Checks on all PRs @@ -256,20 +305,29 @@ These run on every PR and on pushes to `main`: #### CLA check in CI -When you open a pull request (PR) against the `main` branch, a mandatory automated check verifies that you have signed the CLA. It uses the [canonical/has-signed-canonical-cla](https://github.com/canonical/has-signed-canonical-cla) GitHub Action. +When you open a pull request (PR) against the `main` branch, a mandatory automated check +verifies that you have signed the CLA. It uses the +[canonical/has-signed-canonical-cla](https://github.com/canonical/has-signed-canonical-cla) +GitHub Action. If you haven't signed the CLA: 1. The check will fail with a message indicating the CLA requirement 2. Visit to review and sign the agreement -3. Once signed, re-run the check if you have permissions, or ask a maintainer to do so. Pushing a new commit also triggers re-evaluation. +3. Once signed, re-run the check if you have permissions, or ask a maintainer to do so. + Pushing a new commit also triggers re-evaluation. -The CLA check only runs on PRs to `main`. Internal team members working on other branches should ensure they have signed the CLA before their changes are merged to `main`. +The CLA check only runs on PRs to `main`. Internal team members working on other +branches should ensure they have signed the CLA before their changes are merged to +`main`. ### Checks on changes to `docs/` only - Markdown style check: Runs `pymarkdownlnt` on Markdown files -- Automatic documentation checks: Runs upstream documentation workflow checks. - The project uses [canonical/documentation-workflows](https://github.com/canonical/documentation-workflows) for automatic documentation checks. To modify this part of CI behavior, pass inputs to upstream workflows rather than creating or customizing local copies. +- Automatic documentation checks: Runs upstream documentation workflow checks.The + project uses + [canonical/documentation-workflows](https://github.com/canonical/documentation-workflows) + for automatic documentation checks. To modify this part of CI behavior, pass inputs to + upstream workflows rather than creating or customizing local copies. ### Optional checks (allowed to fail) @@ -282,27 +340,21 @@ PRs are typically reviewed within a week. ### Responding to feedback -Push additional commits to address feedback (commit locally rather than via GitHub UI to avoid sync conflicts). +Push additional commits to address feedback (commit locally rather than via GitHub UI to +avoid sync conflicts). -Rebase your branch before requesting a review to keep your commits clean. Once review has started, avoid rebasing to maintain the review history and make it easier for reviewers to see what changed. +Rebase your branch before requesting a review to keep your commits clean. Once review +has started, avoid rebasing to maintain the review history and make it easier for +reviewers to see what changed. ### Common feedback themes Reviewers may request: - Wording, terminology, or formatting changes -- Consistency with existing documentation patterns +- Consistency with existing patterns - Proper reST or MyST markup style - Minimal examples before listing options -- Terminology: Align naming with existing documentation and code - Cross-references: Use proper reST or MyST syntax - Examples: Start minimal, then show options; include verification steps - Theme compatibility: Test in both light and dark modes - -## Release process - - - -## Branch management policy - - From d4ec6275579f30b22c100795d50eb067dcc4f8f9 Mon Sep 17 00:00:00 2001 From: jahn-junior Date: Wed, 29 Apr 2026 19:12:02 -0700 Subject: [PATCH 05/10] chore: rework conf.py comments --- docs/conf.py | 64 ++++++++++++++++------------------------------------ 1 file changed, 19 insertions(+), 45 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 1d3f0b2a..78f85b28 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -19,17 +19,16 @@ ####################### # Project name -# -# TODO: Update with the official name of your project or product (e.g., "Ubuntu Server")_ +# TODO: Update with the official name of your project or product (e.g., "Ubuntu Server") project = "" -author = "Canonical" +# Author name; used in the default copyright statement in the page footer +author = "Canonical Ltd." # The year in the copyright statement copyright = f"{datetime.date.today().year}" # Sidebar documentation title -# # To disable the title, set it to an empty string. html_title = project + " documentation" @@ -37,17 +36,14 @@ ogp_site_url = os.environ.get("READTHEDOCS_CANONICAL_URL", "/") # Preview name of the documentation website -# # TODO: To use a different name for the project in previews, update the next line. ogp_site_name = project # Preview image URL -# # TODO: To customise the preview image, update the next line. ogp_image = "https://assets.ubuntu.com/v1/cc828679-docs_illustration.svg" # Product favicon -# # TODO: To customise the favicon, uncomment and update the next line. # html_favicon = ".sphinx/_static/favicon.png" @@ -55,68 +51,47 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_context html_context = { # Product page URL; can be different from product docs URL - # # TODO: Change to your product website URL, dropping the 'https://' prefix (e.g., # 'ubuntu.com/lxd'). - # # TODO: If there's no such website, remove the {{ product_page }} link from the # .sphinx/_templates/header.html file. "product_page": "", - # Product tag image; the orange part of your logo, shown in the page header - # # TODO: To add a tag image, uncomment and update as needed. # 'product_tag': '_static/tag.png', - # Your Discourse instance URL - # # TODO: Change to your Discourse instance URL or leave empty. "discourse": "", - # Your Mattermost channel URL - # # TODO: Change to your Mattermost channel URL or leave empty. "mattermost": "", - # Your Matrix channel URL - # # TODO: Change to your Matrix channel URL or leave empty. "matrix": "", - # Your documentation GitHub repository URL - # # TODO: Change to your documentation GitHub repository URL or leave empty. - # # NOTE: If set, links for viewing the documentation source files # and creating GitHub issues are added at the bottom of each page. "github_url": "", - # Docs branch in the repo; used in links for viewing the source files - 'repo_default_branch': 'main', - + "repo_default_branch": "main", # Docs location in the repo; used in links for viewing the source files "repo_folder": "/docs/", - # TODO: To enable or disable the Previous / Next buttons at the bottom of pages # Valid options: none, prev, next, both # "sequential_nav": "", - # TODO: To enable listing contributors on individual pages, set to True "display_contributors": False, - - # Required for feedback button - 'github_issues': 'enabled', - + # Required for feedback button + "github_issues": "enabled", # Passes the top-level 'author' value to the theme "author": author, - # Documentation license information "license": { # TODO: Specify your project's license. # For the name, we recommend using the standard shorthand identifier from # https://spdx.org/licenses "name": "", - # TODO: Link directly to your project's license statement. "url": "", }, @@ -134,9 +109,8 @@ # } # Project slug -# # TODO: If your documentation is hosted on https://documentation.ubuntu.com/, -# uncomment and update as needed. +# uncomment and set to the RTD slug. # slug = '' ####################### @@ -147,16 +121,17 @@ html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "/") # sphinx-sitemap uses html_baseurl to generate the full URL for each page: -sitemap_url_scheme = '{link}' +sitemap_url_scheme = "{link}" # Include `lastmod` dates in the sitemap: sitemap_show_lastmod = True -# Exclude generated pages from the sitemap: +# TODO: Exclude pages that aren't user-facing from the sitemap. +# Pages excluded from the sitemap: sitemap_excludes = [ - '404/', - 'genindex/', - 'search/', + "404/", + "genindex/", + "search/", ] ################################ @@ -193,11 +168,15 @@ "https://example.com", # SourceForge domains often block linkcheck r"https://.*\.sourceforge\.(net|io)/.*", - ] +] # A regex list of URLs where anchors are ignored by 'make linkcheck' linkcheck_anchors_ignore_for_url = [r"https://github\.com/.*"] +# Give linkcheck multiple tries on failure. +# TODO: Uncomment if links are frequently timing out. +# linkcheck_timeout = 30 + # Give linkcheck multiple tries on failure linkcheck_retries = 3 @@ -207,12 +186,10 @@ # Custom MyST syntax extensions; see # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html -# # NOTE: By default, the following MyST extensions are enabled: # - substitution # - deflist # - linkify -# # myst_enable_extensions = set() # Custom Sphinx extensions; see @@ -263,19 +240,16 @@ """ # Feedback button at the top; enabled by default -# -# TODO: To disable the button, uncomment the next line. +# TODO: Disable the button if your project is unsuitable for public feedback. # disable_feedback_button = True # Your manpage URL -# # TODO: To enable manpage links, uncomment and replace {codename} with required # release, preferably an LTS release (e.g. noble). Do *not* substitute # {section} or {page}; these will be replaced by sphinx at build time # # NOTE: If set, adding ':manpage:' to an .rst file # adds a link to the corresponding man section at the bottom of the page. - # manpages_url = 'https://manpages.ubuntu.com/manpages/{codename}/en/' + \ # 'man{section}/{page}.{section}.html' From 22dfc420c925ff7fcfb828821a85a0ad919470c2 Mon Sep 17 00:00:00 2001 From: jahn-junior Date: Wed, 29 Apr 2026 19:15:22 -0700 Subject: [PATCH 06/10] docs: tweak sitemap_excludes comment --- docs/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 78f85b28..5988c96a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -126,7 +126,8 @@ # Include `lastmod` dates in the sitemap: sitemap_show_lastmod = True -# TODO: Exclude pages that aren't user-facing from the sitemap. +# TODO: Exclude pages that aren't user-facing from the sitemap (e.g., module pages +# generated by autodoc). # Pages excluded from the sitemap: sitemap_excludes = [ "404/", From 754a20c1554324ae7fd35a5dc0e1a259ca15dab0 Mon Sep 17 00:00:00 2001 From: jahn-junior Date: Thu, 30 Apr 2026 08:16:45 -0700 Subject: [PATCH 07/10] docs: update 'linkcheck_timeout' comment --- docs/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index d452f336..7202db57 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -174,8 +174,8 @@ # A regex list of URLs where anchors are ignored by 'make linkcheck' linkcheck_anchors_ignore_for_url = [r"https://github\.com/.*"] -# Give linkcheck multiple tries on failure. -# TODO: Uncomment if links are frequently timing out. +# How long the link checker will wait for a response for each request +# TODO: Decrease to improve run time or increase if links frequently time out. # linkcheck_timeout = 30 # Give linkcheck multiple tries on failure From 8719f139fbc488d9189f59064435480b7709f70c Mon Sep 17 00:00:00 2001 From: jahn-junior Date: Thu, 30 Apr 2026 13:42:59 -0700 Subject: [PATCH 08/10] docs: replace instances of 'Starter Pack' --- LICENSE | 20 --- docs/.sphinx/update_sp.py | 23 +-- docs/conf.py | 2 +- docs/reuse/components.yaml | 67 -------- docs/reuse/links.txt | 46 ----- docs/reuse/mermaid.txt | 313 ---------------------------------- docs/reuse/substitutions.txt | 7 - docs/reuse/substitutions.yaml | 4 - 8 files changed, 13 insertions(+), 469 deletions(-) delete mode 100644 docs/reuse/components.yaml delete mode 100644 docs/reuse/links.txt delete mode 100644 docs/reuse/mermaid.txt delete mode 100644 docs/reuse/substitutions.txt delete mode 100644 docs/reuse/substitutions.yaml diff --git a/LICENSE b/LICENSE index 31081ad4..f288702d 100644 --- a/LICENSE +++ b/LICENSE @@ -1,13 +1,3 @@ -License for Canonical Starter Pack -================================== - -Unless otherwise stated, all code in this repository is licensed under -the following GPL license. -Documentation for this project is licensed under CC-BY-SA 3.0. - -Starter Pack code ------------------ - GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007 @@ -682,13 +672,3 @@ may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. But first, please read . - -Starter Pack documentation --------------------------- - -Copyright 2024 Canonical Ltd. - -This work is licensed under the Creative Commons Attribution-Share Alike 3.0 -Unported License. To view a copy of this license, visit -http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative -Commons, 171 Second Street, Suite 300, San Francisco, California, 94105, USA. \ No newline at end of file diff --git a/docs/.sphinx/update_sp.py b/docs/.sphinx/update_sp.py index a9259d02..1be1e0a3 100755 --- a/docs/.sphinx/update_sp.py +++ b/docs/.sphinx/update_sp.py @@ -1,28 +1,29 @@ #! /usr/bin/env python -# Initial update script for the starter pack. +# Initial update script for the Sphinx Stack. # # Requires some manual intervention, but makes identifying updates and differences easier. # # For debugging, please run this script with DEBUGGING=1 -# e.g. user@device:~/git/Canonical/sphinx-docs-starter-pack/docs$ DEBUGGING=1 python .sphinx/update_sp.py +# e.g. user@device:~/git/Canonical/sphinx-stack/docs$ DEBUGGING=1 python .sphinx/update_sp.py import glob import logging import os -import requests import re import subprocess import sys -from requests.exceptions import RequestException + +import requests from packaging.version import parse as parse_version +from requests.exceptions import RequestException SPHINX_DIR = os.path.abspath(os.path.dirname(__file__)) -DOCS_DIR = os.path.abspath(os.path.join(SPHINX_DIR, '..')) +DOCS_DIR = os.path.abspath(os.path.join(SPHINX_DIR, "..")) REQUIREMENTS = os.path.join(DOCS_DIR, "requirements.txt") SPHINX_UPDATE_DIR = os.path.join(SPHINX_DIR, "update") -GITHUB_REPO = "canonical/sphinx-docs-starter-pack" +GITHUB_REPO = "canonical/sphinx-stack" GITHUB_API_BASE = f"https://api.github.com/repos/{GITHUB_REPO}" GITHUB_API_SPHINX_DIR = f"{GITHUB_API_BASE}/contents/docs/.sphinx" GITHUB_RAW_BASE = f"https://raw.githubusercontent.com/{GITHUB_REPO}/main" @@ -43,7 +44,7 @@ def main(): except FileNotFoundError: print("WARNING\nWARNING\nWARNING") print( - "You need to update to at least version 1.0.0 of the starter pack to start using the update function." + "You need to update to at least version 1.0.0 of the Sphinx Stack to start using the update function." ) print("You may experience issues using this functionality.") logging.debug("No local version found. Setting version to None") @@ -61,7 +62,7 @@ def main(): logging.debug("Comparing versions") if parse_version(local_version) < parse_version(latest_release): logging.debug("Local version is older than the release version.") - print("Starter pack is out of date.\n") + print("Sphinx Stack is out of date.\n") # Identify and download '.sphinx' dir files to '.sphinx/update' files_updated, new_files = update_static_files() @@ -130,7 +131,7 @@ def main(): except FileNotFoundError: print("requirements.txt not found") print( - "The updated starter pack has moved requirements.txt out of the '.sphinx' dir" + "The updated Sphinx Stack has moved requirements.txt out of the '.sphinx' dir" ) print("requirements.txt not checked, please update your requirements manually") @@ -142,7 +143,7 @@ def update_static_files(): for item in query_api(GITHUB_API_SPHINX_DIR).json(): logging.debug(f"Checking {item['name']}") - # Checks existing files in '.sphinx' starter pack static root for changed SHA + # Checks existing files in '.sphinx' Sphinx Stack static root for changed SHA if item["name"] in files and item["type"] == "file": index = files.index(item["name"]) if item["sha"] != get_git_revision_hash(paths[index]): @@ -189,7 +190,7 @@ def update_static_files(): SPHINX_UPDATE_DIR, item["name"], nested_item["name"] ), ) - # Downloads NEW files in '.sphinx' starter pack static root + # Downloads NEW files in '.sphinx' Sphinx Stack static root else: if item["type"] == "file": logging.debug(f"No local version found of {item['name']}") diff --git a/docs/conf.py b/docs/conf.py index 7202db57..61faabbb 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -105,7 +105,7 @@ # - https://git.launchpad.net/example # # html_theme_options = { -# 'source_edit_link': 'https://github.com/canonical/sphinx-docs-starter-pack', +# 'source_edit_link': 'https://github.com/canonical/sphinx-stack', # } # Project slug diff --git a/docs/reuse/components.yaml b/docs/reuse/components.yaml deleted file mode 100644 index d9755648..00000000 --- a/docs/reuse/components.yaml +++ /dev/null @@ -1,67 +0,0 @@ -documentation_architecture: - - diagram_name: "Sphinx" - description: "The core process of transforming source files into HTML using Sphinx." - mermaid_code: | - graph LR - A["Source Files
    (.rst or .md)"] -->|provides content to| C[Sphinx] - B["Configuration
    (docs/conf.py)"] -->|provides settings to| C - C -->|generates| D[Built HTML Pages] - rendered_image: "../explanation/assets/sphinx.png" - - - diagram_name: "Python environment" - description: "The relationship between the host system and the virtual environment." - mermaid_code: | - graph LR - subgraph Host ["Host"] - direction LR - pip[pip] -->|installs| PD["Project dependencies"] - python3[python3] --> Sphinx - venv[venv] -->|creates| VE["Virtual environment"] - subgraph VE ["Virtual environment"] - direction LR - PD -->|extend| Sphinx - end - Sphinx -->|builds| HTML[HTML] - end - rendered_image: "../explanation/assets/python-starter-pack.png" - - - diagram_name: "Extensions" - description: "How built-in and third-party extensions are integrated and activated via requirements and conf.py." - mermaid_code: | - graph TD - Python -->|installs the contents of| Reqs[/"requirements.txt"\] - Reqs -->|specifies| ThirdParty["Third-party extensions"] - Sphinx -->|provides| BuiltIn["Built-in Sphinx extensions"] - subgraph Deps ["Various dependencies"] - BuiltIn - ThirdParty - end - BuiltIn -->|are activated in| Conf[/"Project configuration file (docs/conf.py)"\] - ThirdParty -->|are activated in| Conf - rendered_image: "../explanation/assets/extensions.png" - - - diagram_name: "Read the Docs" - description: "Details the declaration of build logic in the RTD configuration file for hosting." - mermaid_code: | - graph TD - Sphinx -->|is declared in| RTD_Conf[/"RTD configuration file (.readthedocs.yaml)"\] - Conf_py["conf.py"] -->|is declared in| RTD_Conf - Python_Ver["Python version"] -->|is declared in| RTD_Conf - RTD_Conf -->|defines the build logic for| RTD["Read the Docs (RTD)"] - RTD -->|builds and hosts| HTML[/"HTML"\] - rendered_image: "../explanation/assets/rtd-build.png" - - - diagram_name: "Third-party extensions" - description: "Focuses on the specific installation path for external dependencies via pip and requirements." - mermaid_code: | - graph TD - Python[Python] - Reqs[/"requirements.txt"\] - Sphinx[Sphinx] - subgraph Deps ["Various dependencies"] - BuiltIn["Built-in Sphinx extensions"] - ThirdParty["Third-party extensions"] - end - Python -->|installs the contents of| Reqs - Reqs -->|specifies| ThirdParty - rendered_image: "../explanation/assets/third-party-extensions.png" \ No newline at end of file diff --git a/docs/reuse/links.txt b/docs/reuse/links.txt deleted file mode 100644 index af3c3b54..00000000 --- a/docs/reuse/links.txt +++ /dev/null @@ -1,46 +0,0 @@ -.. _Canonical Documentation Style Guide: https://docs.ubuntu.com/styleguide/en -.. _Canonical Reference Library: https://library.canonical.com/ -.. _Canonical Sphinx: https://github.com/canonical/canonical-sphinx -.. _change log: https://github.com/canonical/sphinx-docs-starter-pack/wiki/Change-log -.. _csv-table reference: https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table -.. _csv-table reference (MyST): https://mystmd.org/guide/directives#directive-csv-table -.. _Diátaxis: https://diataxis.fr/ -.. _Example product documentation: https://canonical-example-product-documentation.readthedocs-hosted.com/ -.. _Example product documentation repository: https://github.com/canonical/example-product-documentation -.. _`file-wide metadata`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html -.. _Five golden rules for compliant alt text: https://abilitynet.org.uk/resources/digital-accessibility/five-golden-rules-compliant-alt-text -.. _`Furo documentation`: https://pradyunsg.me/furo/quickstart/ -.. _grid tables: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#grid-tables -.. _`Hiding Contents sidebar`: https://pradyunsg.me/furo/customisation/toc/ -.. _How to connect your Read the Docs account to your Git provider: https://docs.readthedocs.com/platform/stable/guides/connecting-git-account.html -.. _How to manually configure a Git repository integration: https://docs.readthedocs.com/platform/stable/guides/setup/git-repo-manual.html -.. _How to publish documentation on Read the Docs: https://library.canonical.com/documentation/publish-on-read-the-docs -.. _Level AA conformance: https://www.w3.org/WAI/WCAG2AA-Conformance -.. _list tables: https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table -.. _manual import: https://readthedocs.com/dashboard/import/manual/ -.. _Markdown: https://commonmark.org/ -.. _MyST: https://myst-parser.readthedocs.io/ -.. _Open Graph: https://ogp.me/ -.. _Pa11y: https://pa11y.org/ -.. _Pa11y readme: https://github.com/pa11y/pa11y#command-line-configuration -.. _Pygments documentation: https://pygments.org/languages/ -.. _Read the Docs at Canonical: https://library.canonical.com/documentation/read-the-docs-at-canonical -.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html -.. _`Sphinx`: https://www.sphinx-doc.org/ -.. _`Sphinx configuration`: https://www.sphinx-doc.org/en/master/usage/configuration.html -.. _Sphinx DataTables: https://sharm294.github.io/sphinx-datatables/ -.. _Sphinx design: https://sphinx-design.readthedocs.io/en/latest/ -.. _Sphinx documentation starter pack: -.. _Sphinx documentation starter pack repository: https://github.com/canonical/sphinx-docs-starter-pack -.. _Sphinx documentation starter pack documentation: https://canonical-starter-pack.readthedocs-hosted.com/ -.. _`Sphinx extensions`: https://www.sphinx-doc.org/en/master/usage/extensions/index.html -.. _Sphinx tabs: https://sphinx-tabs.readthedocs.io/en/latest/ -.. _tables: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#table-directives -.. _toctree: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree -.. _Vale: https://vale.sh/ -.. _Vale rules: https://github.com/canonical/documentation-style-guide -.. _Web Content Accessibility Guidelines (WCAG) 2.2: https://www.w3.org/TR/WCAG22/ - - -.. SHORTCUTS -.. |RST| replace:: :abbr:`reST (reStructuredText)` diff --git a/docs/reuse/mermaid.txt b/docs/reuse/mermaid.txt deleted file mode 100644 index 68ec1b56..00000000 --- a/docs/reuse/mermaid.txt +++ /dev/null @@ -1,313 +0,0 @@ -mermaid-diagram-flowchart-start -``````{tab-set} - -`````{tab-item} Diagram -```{image} https://assets.ubuntu.com/v1/34c7105c-screenshot_from_2025_10_13_15_05_56.png -``` -````` - -`````{tab-item} MyST - -````{code-block} md -```{mermaid} -flowchart LR - A([New PR]) - B[Needs review] - C{Review approved?} - D{Merge conflicts?} - E[Needs work] - F[Needs CI] - G{Passed testing?} - H[Ready for merge] - I[(PR merged)] - J{Comments addressed?} - K[(PR closed)] - - A --> B - B --> C - C -- no --> E - C -- yes --> D - D -- yes --> E - D -- no --> F - F --> G - G -- yes --> H - G -- no --> E - H --> I - E --> J - J -- yes --> B - J -- no --> K -``` -```` - -````` - -`````{tab-item} rST - -````{code-block} rst -.. mermaid:: - - flowchart LR - A([New PR]) - B[Needs review] - C{Review approved?} - D{Merge conflicts?} - E[Needs work] - F[Needs CI] - G{Passed testing?} - H[Ready for merge] - I[(PR merged)] - J{Comments addressed?} - K[(PR closed)] - - A --> B - B --> C - C -- no --> E - C -- yes --> D - D -- yes --> E - D -- no --> F - F --> G - G -- yes --> H - G -- no --> E - H --> I - E --> J - J -- yes --> B - J -- no --> K -```` - -````` -`````` -mermaid-diagram-flowchart-end - -mermaid-diagram-sequence-start -``````{tab-set} - -`````{tab-item} Diagram - -```{image} https://assets.ubuntu.com/v1/a7eb0fcf-screenshot_from_2025_10_13_15_08_06.png -``` - -````` - -`````{tab-item} Custom CSS - -First, create a Mermaid stylesheet in the {file}`_static` directory and -customize it as needed. For example, {file}`mermaid-sequence.css`. - -Then, enable custom stylesheets in {file}`conf.py`. -Uncomment this line so Sphinx can use local stylesheets: - -```{code-block} py -:caption: conf\.py - -html_static_path = ["_static"] -``` - -Link to your custom Mermaid stylesheet: - -```{code-block} py -:caption: conf\.py - -html_css_files = [ - "mermaid-sequence.css", -] -``` - -Here's an example stylesheet that changes the default typefaces and colors of Mermaid components. -It also sets a solid background color for all Mermaid diagrams. - -```{code-block} css -:caption: mermaid-sequence.css - -.actor { - stroke: #eb6536 !important; - stroke-width: 2; - fill: #f5b29b !important; -} - -text.actor { - fill: black; - stroke: none; - font-family: Helvetica; -} - -.actor-line { - stroke: #77216f; -} - -.mermaid { - background-color: #f0f0f0; - border: 1px solid #ccc; - border-radius: 6px; - padding: 0.5em; -} -``` -````` - -`````{tab-item} MyST - -````{code-block} md -```{mermaid} -sequenceDiagram - participant User - participant Snap as snapd (Client) - participant Store as Snap Store - participant System - - User->>Snap: snap install hello - Snap->>Store: Request snap info and download - Store-->>Snap: Return snap package - Snap->>System: Install and mount snap - System-->>Snap: Installation result - Snap-->>User: Confirm snap is installed -``` -```` - -````` - -`````{tab-item} rST - -````{code-block} rst -.. mermaid:: - - sequenceDiagram - participant User - participant Snap as snapd (Client) - participant Store as Snap Store - participant System - - User->>Snap: snap install hello - Snap->>Store: Request snap info and download - Store-->>Snap: Return snap package - Snap->>System: Install and mount snap - System-->>Snap: Installation result - Snap-->>User: Confirm snap is installed -```` - -````` -`````` -mermaid-diagram-sequence-end - -mermaid-diagram-timeline-start -``````{tab-set} - -`````{tab-item} Diagram - -```{image} https://assets.ubuntu.com/v1/24895eed-screenshot_from_2025_10_13_15_06_35.png -``` - -````` - -`````{tab-item} MyST - -````{code-block} md -:emphasize-lines: 2 -```{mermaid} -%%{init: {"theme":"forest"}}%% -timeline - title Ubuntu recent releases - - 2020 : 20.04 LTS (Focal Fossa) : 20.10 (Groovy Gorilla) - 2021 : 21.04 (Hirsute Hippo) : 21.10 (Impish Indri) - 2022 : 22.04 LTS (Jammy Jellyfish) : 22.10 (Kinetic Kudu) - 2023 : 23.04 (Lunar Lobster) : 23.10 (Mantic Minotaur) - 2024 : 24.04 LTS (Noble Numbat) : 24.10 (Oracular Oriole) - 2025 : 25.04 (Plucky Puffin) -``` -```` - -````` - -`````{tab-item} rST - -````{code-block} rst -:emphasize-lines: 3 - -.. mermaid:: - - %%{init: {"theme":"forest"}}%% - timeline - title Ubuntu recent releases - - 2020 : 20.04 LTS (Focal Fossa) : 20.10 (Groovy Gorilla) - 2021 : 21.04 (Hirsute Hippo) : 21.10 (Impish Indri) - 2022 : 22.04 LTS (Jammy Jellyfish) : 22.10 (Kinetic Kudu) - 2023 : 23.04 (Lunar Lobster) : 23.10 (Mantic Minotaur) - 2024 : 24.04 LTS (Noble Numbat) : 24.10 (Oracular Oriole) - 2025 : 25.04 (Plucky Puffin) -```` - -````` -`````` -mermaid-diagram-timeline-end - -mermaid-diagram-state-start -``````{tab-set} - -`````{tab-item} Diagram - -```{image} https://assets.ubuntu.com/v1/dd4fb237-screenshot_from_2025_10_13_15_08_51.png -``` - -````` - -`````{tab-item} MyST - -````{code-block} md -:emphasize-lines: 3-6, 17-20 - -```{mermaid} -stateDiagram-v2 - classDef review fill:#FCE83A - classDef approved fill:#2DCCFF - classDef published fill:#56F000 - classDef archived fill:#7B8089 - - [*] --> Draft - Draft --> Review : submit for review - Review --> Draft : changes requested - Review --> Approved : review passed - Approved --> Build : trigger build - Build --> Published : build success - Build --> Draft : build failed - Published --> Archived : old version - - class Review review - class Approved approved - class Published published - class Archived archived -``` -```` - -````` - -`````{tab-item} rST - -````{code-block} rst -:emphasize-lines: 4-7, 18-21 - -.. mermaid:: - - stateDiagram-v2 - classDef review fill:#FCE83A - classDef approved fill:#2DCCFF - classDef published fill:#56F000 - classDef archived fill:#7B8089 - - [*] --> Draft - Draft --> Review : submit for review - Review --> Draft : changes requested - Review --> Approved : review passed - Approved --> Build : trigger build - Build --> Published : build success - Build --> Draft : build failed - Published --> Archived : old version - - class Review review - class Approved approved - class Published published - class Archived archived -```` - -````` -`````` -mermaid-diagram-state-end \ No newline at end of file diff --git a/docs/reuse/substitutions.txt b/docs/reuse/substitutions.txt deleted file mode 100644 index 307b5f2e..00000000 --- a/docs/reuse/substitutions.txt +++ /dev/null @@ -1,7 +0,0 @@ -.. |version_number| replace:: 0.1.0 - -.. |rest_text| replace:: *Multi-line* text - that uses basic **markup**. - -.. |site_link| replace:: Website link -.. _site_link: https://example.com \ No newline at end of file diff --git a/docs/reuse/substitutions.yaml b/docs/reuse/substitutions.yaml deleted file mode 100644 index 0c2958d2..00000000 --- a/docs/reuse/substitutions.yaml +++ /dev/null @@ -1,4 +0,0 @@ -# Key/value substitutions to use within the Sphinx doc. -{version_number: "0.1.0", - formatted_text: "*Multi-line* text\n that uses basic **markup**.", - site_link: "[Website link](https://example.com)"} \ No newline at end of file From cf5759aba933bdf884ec55ca641c14ecb8caa1c2 Mon Sep 17 00:00:00 2001 From: Michael DuBelko Date: Thu, 30 Apr 2026 16:54:38 -0700 Subject: [PATCH 09/10] docs: comment out rst_epilog --- docs/conf.py | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 61faabbb..e984ccad 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -234,11 +234,9 @@ # "https://assets.ubuntu.com/v1/287a5e8f-bundle.js", # ] -# Specifies a reST snippet to be appended to each .rst file -rst_epilog = """ -.. include:: /reuse/links.txt -.. include:: /reuse/substitutions.txt -""" +# Appends extra markup to the end of every document written in reST +#rst_epilog = """ +#""" # Feedback button at the top; enabled by default # TODO: Disable the button if your project is unsuitable for public feedback. From 4af3f5a926c3a2245d3cd14a5f0c887585322f04 Mon Sep 17 00:00:00 2001 From: jahn-junior Date: Thu, 30 Apr 2026 17:06:17 -0700 Subject: [PATCH 10/10] docs: improve placeholders --- docs/conf.py | 2 +- docs/index.rst | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index e984ccad..43ed0add 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -20,7 +20,7 @@ # Project name # TODO: Update with the official name of your project or product (e.g., "Ubuntu Server") -project = "" +project = "Project" # Author name; used in the default copyright statement in the page footer author = "Canonical Ltd." diff --git a/docs/index.rst b/docs/index.rst index 9a54f503..027f9aa3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,5 +1,5 @@ - -============== +Project +======= In this documentation