From 70ab145121a01bc9887024ca3c625e18e0d7240e Mon Sep 17 00:00:00 2001 From: Andreia Velasco Date: Fri, 17 Jul 2026 15:05:07 +0200 Subject: [PATCH 1/4] add canary page changes --- docs/canary-page.md | 694 ++++++++++++++++++++++++++++++++++++++++++++ docs/conf.py | 25 +- docs/hidden-page.md | 8 + docs/index.rst | 7 + docs/redirects.txt | 6 +- 5 files changed, 728 insertions(+), 12 deletions(-) create mode 100644 docs/canary-page.md create mode 100644 docs/hidden-page.md diff --git a/docs/canary-page.md b/docs/canary-page.md new file mode 100644 index 00000000..33f80561 --- /dev/null +++ b/docs/canary-page.md @@ -0,0 +1,694 @@ +--- +relatedlinks: "[Example link](https://example.com)" +hide-toc: true +--- + +# Test page for default extensions + +This page contains basic example structures from every MyST and rST extension that is included in the Sphinx Stack by default. + +## `canonical_sphinx` + +Below are the default extensions bundled into `canonical_sphinx`. + +### Furo theme + +This is partially tested by setting Furo's `hide-toc` feature to `true` in this page's metadata. + +**Expectation**: The right side of the page should **not** contain a table of contents. + +**HTML check**: The HTML of this page does **not** contain the following `
` classes: + +```html +
+ (...) +
+ (...) +``` + +### MyST parser + +This is tested with the `{sub-ref}` MyST directive to count words through `wordcount-words`. + +**Expectation**: There is a number in the sentence "This page has {sub-ref}`wordcount-words` words". + +### linkify-it-py + +This is tested by writing a URL in plain text and checking that it turns into a link. + +**Expectation**: //localhost is a clickable link. + +**HTML check**: + +```html +//localhost +``` + +## `notfound.extension` + +This is tested by accessing a non-existent sub-page of this documentation set. + +**Expectation**: https://documentation.ubuntu.com/sphinx-stack/a renders a "Page not found" message with the same CSS styling as the rest of the documentation, maintaining the left-side navigation and upper menu. + +## `sphinx_design` + +This is tested by rendering sample structures based on [`sphinx-design` documentation examples](https://sphinx-design.readthedocs.io/en/latest/index.html). + +### Grids + +#### Basic grid + +**Expectation**: The following grids have an outer outline and three grid items. + +````{grid} +:outline: + +```{grid-item} +MyST grid item 1 +``` +```{grid-item} +MyST grid item 2 +``` +```{grid-item} +MyST grid item 3 +``` +```` + +```{eval-rst} +.. grid:: + :outline: + + .. grid-item:: + reST grid item 1 + + .. grid-item:: + reST grid item 2 + + .. grid-item:: + reST grid item 3 +``` + +**HTML check**: + +```html +
+ (...) +``` + +#### Card grids + +**Expectation**: The following grids are composed of cards. + +````{grid} +```{grid-item-card} Title 1 +MyST grid item card 1 +``` +```{grid-item-card} Title 2 +MyST grid item card 2 +``` +```{grid-item-card} Title 3 +MyST grid item card 3 +``` +```` + +```{eval-rst} +.. grid:: + + .. grid-item-card:: Title 1 + + reST grid item card 1 + + .. grid-item-card:: Title 2 + + reST grid item card 2 + + .. grid-item-card:: Title 3 + + reST grid item card 3 +``` + +**HTML check**: + +```html +
+ (...) +``` + +### Cards + +#### Basic card + +```{card} MyST card title +Card content +``` + +```{eval-rst} +.. card:: reST card title + + Card content +``` + +**HTML check**: + +```html +
+ (...) +``` + +#### Card with header and footer + +**Expectation**: The following cards have header and footer text. + +```{card} MyST card title +Header +^^^ +Card content ++++ +Footer +``` + +```{eval-rst} +.. card:: reST card title + + Header + ^^^ + Card content + +++ + Footer +``` + +**HTML check**: + +```html +
+ (...) +
+``` + +#### Clickable card + +**Expectation**: The following cards are clickable, and links to documentation.ubuntu.com/sphinx-stack: + +```{card} Click me +:link: https://documentation.ubuntu.com/sphinx-stack/ + +This MyST card links to `https://documentation.ubuntu.com/sphinx-stack/` +``` + +```{eval-rst} +.. card:: Click me + :link: https://documentation.ubuntu.com/sphinx-stack/ + + This reST card links to ``https://documentation.ubuntu.com/sphinx-stack/`` +``` + +**HTML check**: + +```html + + https://documentation.ubuntu.com/sphinx-stack/latest/ + +``` +### Dropdowns + +#### Basic dropdown + +**Expectation**: The dropdowns are open by default. + +```{dropdown} MyST dropdown title +:open: + +Dropdown content +``` + +```{eval-rst} +.. dropdown:: reST dropdown title + :open: + + Dropdown content +``` + +**HTML check**: + +```html +
+ (...) +``` + +#### Custom dropdown + +**Expectation**: The dropdowns are closed by default, have a grey title card, and a wrench icon. + +```{dropdown} MyST dropdown title +:icon: tools +:color: secondary + +Dropdown content +``` + +```{eval-rst} +.. dropdown:: reST dropdown title + :icon: tools + :color: secondary + + Dropdown content +``` + +**HTML check**: + +```html + + (...) + + (...) +``` + +### Tabs + +**Expectation**: The following MyST tab sets synchronize with each other: + +````{tab-set} +```{tab-item} MyST label 1 +:sync: myst-label-1 + +MyST tab content 1 +``` +```{tab-item} MyST label 2 +:sync: myst-label-2 + +MyST tab content 2 +``` +```` + +`````{tab-set} +````{tab-item} MyST label 1 +:sync: myst-label-1 + +This MyST tab includes a code block: +```{code-block} python +print("hello") +``` +```` +````{tab-item} MyST label 2 +:sync: myst-label-2 + +```{card} +This MyST card is inside a MyST tab. +``` +```` +````` + +```{eval-rst} +**Expectation**: The following reST tab sets synchronize with each other: + +.. tab-set:: + + .. tab-item:: reST label 1 + :sync: rest-label-1 + + reST tab content 1 + + .. tab-item:: reST label 2 + :sync: rest-label-2 + + reST tab content 2 + +.. tab-set:: + + .. tab-item:: reST label 1 + :sync: rest-label-1 + + This reST tab includes a code block: + + .. code-block:: python + + print("hello") + + .. tab-item:: reST label 2 + :sync: rest-label-2 + + .. card:: + This reST card is inside a reST tab. +``` + +### Badges, Buttons and Icons + +#### Inline badges + +**Expectation**: Blue badge labelled "info" and white badge with a blue outline labelled "info-line" are visible. + +MyST badges: {bdg-info}`info`, {bdg-info-line}`info-line` +```{eval-rst} +reST badges: :bdg-info:`info`, :bdg-info-line:`info-line` +``` + +#### Inline clickable badges + +**Expectation**: Blue and white badge with a blue outline, both labelled "https://example.com, are visible and clickable. + +MyST badges: {bdg-link-info}`https://example.com`, {bdg-link-info-line}`https://example.com` +```{eval-rst} +reST badges: :bdg-link-info:`https://example.com`, :bdg-link-info-line:`https://example.com` +``` + +#### Clickable buttons + +**Expectation**: The following buttons are labelled "https://example.com" and are clickable: + +MyST button: + +```{button-link} https://example.com +:color: info +``` +```{eval-rst} +reST button: + +.. button-link:: https://example.com + :color: info +``` + +#### Inline octicons + +**Expectation**: Inline icons of "octicon" style are visible. They are a right arrow, a circle containing a check mark, a gear, and a circle containing an x. + +MyST octicons: {octicon}`arrow-right`, {octicon}`check-circle`, {octicon}`gear`, {octicon}`x-circle` +```{eval-rst} +reST octicons: :octicon:`arrow-right`, :octicon:`check-circle`, :octicon:`gear`, :octicon:`x-circle` +``` + +### Additional + +**Expectation**: A block of information about an article is displayed. It shows an avatar, author, date, and read duration: + +```{article-info} +:avatar: https://assets.ubuntu.com/v1/cc828679-docs_illustration.svg +:avatar-outline: muted +:author: MyST author +:date: Jul 24, 2021 +:read-time: 5 min read +:class-container: sd-p-2 sd-outline-muted +``` + +```{eval-rst} + +.. article-info:: + :avatar: https://assets.ubuntu.com/v1/cc828679-docs_illustration.svg + :avatar-outline: muted + :author: reST author + :date: Jul 24, 2021 + :read-time: 5 min read + :class-container: sd-p-2 sd-outline-muted +``` + +## `sphinx_rerediraffe` + +**Expectation**: + +[canonical-sphinx-stack-testing.readthedocs-hosted.com/agentic-tests/**test-rerediraffe**](https://canonical-sphinx-stack-testing.readthedocs-hosted.com/agentic-tests/test-rerediraffe) + +redirects to + +[canonical-sphinx-stack-testing.readthedocs-hosted.com/agentic-tests/**canary-page**](https://canonical-sphinx-stack-testing.readthedocs-hosted.com/agentic-tests/canary-page). + +## `sphinx_reredirects` + +**Expectation**: + +[canonical-sphinx-stack-testing.readthedocs-hosted.com/agentic-tests/**test-reredirects**](https://canonical-sphinx-stack-testing.readthedocs-hosted.com/agentic-tests/test-reredirects) + +redirects to + +[canonical-sphinx-stack-testing.readthedocs-hosted.com/agentic-tests/**canary-page**](https://canonical-sphinx-stack-testing.readthedocs-hosted.com/agentic-tests/canary-page). + +## `sphinx_tabs.tabs` + +**Expectation**: The following MyST tab sets synchronize with each other: + +````{tabs} +```{group-tab} MyST label 1 +MyST tab content 1 +``` +```{group-tab} MyST label 2 +MyST tab content 2 +``` +```` + +`````{tabs} +````{group-tab} MyST label 1 + +This MyST tab includes a code block: +```{code-block} python +print("hello") +``` +```` +````{group-tab} MyST label 2 + +```{card} +This MyST card is inside a MyST tab. +``` +```` +````` + +```{eval-rst} +**Expectation**: The following reST tab sets synchronize with each other: + +.. tabs:: + .. group-tab:: reST label 1 + + reST tab content 1 + + .. group-tab:: reST label 2 + + reST tab content 2 + +.. tabs:: + .. group-tab:: reST label 1 + + This reST tab includes a code block: + + .. code-block:: python + + print("hello") + + .. group-tab:: reST label 2 + + .. card:: + + This reST card is inside a reST tab. +``` + +## `sphinxext.opengraph` + +**HTML check**: The HTML source of this page should include the following meta tags: + +```html + + + + + + + +``` + +## `sphinx_config_options` + +**Expectation**: Collapsed config option blocks can be expanded to reveal the following parameters: key, type, default, live update, condition, and scope. + +```{config:option} cache.enabled.myst +:shortdesc: Enable or disable caching (MyST) +:type: boolean +:default: false +:scope: server +:liveupdate: true +:condition: Only available with premium license + +Controls whether the application uses caching to improve performance. +``` + +**Expectation**: {config:option}`cache.enabled.myst` should link to the MyST config block. + +```{eval-rst} +.. config:option:: cache.enabled.rest + :shortdesc: Enable or disable caching (reST) + :type: boolean + :default: false + :scope: server + :liveupdate: true + :condition: Only available with premium license + + Controls whether the application uses caching to improve performance. + +**Expectation**: :config:option:`cache.enabled.rest` should link to the reST config block. +``` + +## `sphinx_contributor_listing` + +**Expectation**: The footer of this page should contain clickable text starting with "Thanks to". Clicking it should display a pop-up list of contributors. + +**HTML check**: + +```html + +``` + +## `sphinx_filtered_toctree` + +This is tested by creating the page {ref}`hidden-page` as a sibling of this current page, and hiding it from the TOC with `:exclude:`. + +**Expectation**: The left-side TOC should **not** visibly contain a page called {ref}`hidden-page`. + +**HTML check**: The HTML of this page should **not** contain + +```html +Hidden page +``` + +## `sphinx_llm.txt` + +This is tested by appending `llms-full.txt` to the site root. + +**Expectation**: https://canonical-sphinx-stack-testing.readthedocs-hosted.com/agentic-tests/llms-full.txt contains the documentation in raw markdown text. + +## `sphinx_related_links` + +This is tested by adding `relatedlinks` to this page's metadata with an example link. + +**Expectation**: A "Related links" list can be seen on the right side of this page and contains an example link. + +## `sphinx_roles` + +**Expectation**: The following literal references are links to example.com. + +This is a {literalref}`literal reference in MyST `. + +```{eval-rst} +This is a :literalref:`literal reference in reST `. +``` + +**Expectation**: + +"{spellexception}`Lorem ipsum`" should be excluded from the spell checker (MyST directive). + +```{eval-rst} +":spellexception:`Lorem ipsum`" should be excluded from the spell checker (reST directive). +``` + +**Expectation**: +There should be no inline text following "directive:" + +Phrase hidden by MyST directive: {none}`If you can see this text, you might have an issue with the sphinx_roles extension.` + +```{eval-rst} +Phrase hidden by reST directive: :none:`If you can see this text, you might have an issue with the sphinx_roles extension.` +``` + +## `sphinx_terminal` + +**Expectation**: Dark terminals showing `user@pc` running the command `echo 'hello'` in `~/path`. The output is `hello`. + +The input command `echo 'hello'` can be copied with the copy button on the top right of the terminal: + +```{terminal} +:copy: +:user: user +:host: pc +:dir: ~/path + +echo 'hello MyST' + +hello MyST +``` + +
+ +```{eval-rst} +.. terminal:: + :copy: + :user: user + :host: pc + :dir: ~/path + + echo 'hello reST' + + hello reST +``` + +**Expectation**: The terminals below only show the output: + +```{terminal} +:output-only: + +hello MyST +``` + +
+ +```{eval-rst} +.. terminal:: + :output-only: + + hello reST +``` + +## `sphinx_ubuntu_images` + +**Expectation**: Lists of images for Ubuntu 26.04 LTS (Resolute Raccoon). + +MyST directive output: + +```{ubuntu-images} +:releases: resolute- +``` + +reST directive output: + +```{eval-rst} +.. ubuntu-images:: + :releases: resolute- +``` + +## `sphinx_youtube_links` + +```{youtube} https://www.youtube.com/watch?v=dQw4w9WgXcQ +``` + +**Expectation**: There should be a "Watch on YouTube" button with an orange play icon to the right of this paragraph. This one is generated with MyST. + +This text is written below the ```{youtube} MyST directive. Therefore it should render to the left of the button and wrap around it. + +Text below the button should expand back into taking up the full horizontal length of the section. + +```{eval-rst} +.. youtube:: https://www.youtube.com/watch?v=dQw4w9WgXcQ +``` + +**Expectation**: There should be a second "Watch on YouTube" button with an orange play icon to the right of this paragraph. This one is generated with reST. + +This text is written below the `.. youtube::` reST directive. Therefore it should render to the left of the button and wrap around it. + +Text below the button should expand back into taking up the full horizontal length of the section. + +## `sphinx_last_updated_by_git` + +**Expectation**: The page footer should contain text that says "Last updated on", followed by a date. + +**HTML check**: + +```html + +``` + +## `sphinx.ext.intersphinx` + +**Expectation**: Both intersphinx references below should link to [documentation.ubuntu.com/sphinx-stack/latest/how-to/optional-customisation/external-referencing-intersphinx/](https://documentation.ubuntu.com/sphinx-stack/latest/how-to/optional-customisation/external-referencing-intersphinx/). + +MyST reference: {ref}`sphinx-stack-docs:how-to-link-docs-intersphinx` + +```{eval-rst} +reST reference :ref:`sphinx-stack-docs:how-to-link-docs-intersphinx` +``` + +## `sphinx_sitemap` + +**Expectation**: https://canonical-sphinx-stack-testing.readthedocs-hosted.com/agentic-tests/sitemap.xml contains an XML file listing all pages in this documentation set. \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 926230f4..c470187b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -36,6 +36,7 @@ # 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 @@ -72,16 +73,16 @@ # documentation source files and creating GitHub issues are added at the bottom of # each page. # TODO: Change to your documentation GitHub repository URL or leave empty. - "github_url": "", + "github_url": "github.com/a-velasco/sphinx-stack-testing", # Docs branch in the repo; used in links for viewing the source files "repo_default_branch": "main", # Docs location in the repo; used in links for viewing the source files - "repo_folder": "/docs/", + "github_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, + "display_contributors": True, # Required for feedback button "github_issues": "enabled", # Passes the top-level 'author' value to the theme @@ -140,7 +141,7 @@ ################################ # html_static_path = ["_static"] -# templates_path = ["_templates"] +templates_path = ["_templates"] ############# # Redirects # @@ -157,6 +158,8 @@ # Strips '/index.html' from destination URLs when building with 'dirhtml' rediraffe_dir_only = True +# Redirects via the sphinx_reredirects extension: +redirects = {"test-reredirects": "../canary-page"} ############################ # sphinx-llm configuration # @@ -243,9 +246,11 @@ exclude_patterns = [ "doc-cheat-sheet*", ".venv*", - "_dev", ] +# Excludes files from toctree +toc_filter_exclude = ["exclude"] + # Adds custom CSS files, located remotely or in 'html_static_path'. # html_css_files = [ # "https://assets.ubuntu.com/v1/d86746ef-cookie_banner.css", @@ -288,8 +293,8 @@ :class: vale-ignore """ -# Configuration for Intersphinx projects -# -# intersphinx_mapping = { -# "snap": ("https://snapcraft.io/docs/", None), -# } +#Configuration for Intersphinx projects + +intersphinx_mapping = { + "sphinx-stack-docs": ("https://documentation.ubuntu.com/sphinx-stack/latest/", None), +} \ No newline at end of file diff --git a/docs/hidden-page.md b/docs/hidden-page.md new file mode 100644 index 00000000..471a5449 --- /dev/null +++ b/docs/hidden-page.md @@ -0,0 +1,8 @@ +--- +orphan: True +--- + +(hidden-page)= +# Hidden page + +I'm hidden! \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 027f9aa3..05168c3b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -41,3 +41,10 @@ Governance and policies release-notes/index contribute/index + +.. filtered-toctree:: + :hidden: + :maxdepth: 1 + + Canary page + Hidden page <:exclude:hidden-page> \ No newline at end of file diff --git a/docs/redirects.txt b/docs/redirects.txt index e4e5e8ba..f295e7cf 100644 --- a/docs/redirects.txt +++ b/docs/redirects.txt @@ -3,6 +3,8 @@ # "" "" # # Paths must be represented as source files relative to the root of the docs directory. -# The old path must be a file that doesn't exist in the source. The current path must be -# a file that does exist in the source. Redirecting to a specific section is not supported. +# 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. + +"test-rerediraffe" "canary-page" From f5bc09c73ce01e1c42717a9949791546b6ffbe70 Mon Sep 17 00:00:00 2001 From: Andreia Velasco Date: Fri, 17 Jul 2026 15:24:17 +0200 Subject: [PATCH 2/4] fix spelling and link errors --- docs/canary-page.md | 10 +++++----- docs/conf.py | 2 ++ 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/canary-page.md b/docs/canary-page.md index 33f80561..5d1ebb73 100644 --- a/docs/canary-page.md +++ b/docs/canary-page.md @@ -187,7 +187,7 @@ Footer #### Clickable card -**Expectation**: The following cards are clickable, and links to documentation.ubuntu.com/sphinx-stack: +**Expectation**: The following cards are clickable, and links to documentation.ubuntu.com/sphinx-stack : ```{card} Click me :link: https://documentation.ubuntu.com/sphinx-stack/ @@ -367,13 +367,13 @@ reST button: :color: info ``` -#### Inline octicons +#### Inline icons -**Expectation**: Inline icons of "octicon" style are visible. They are a right arrow, a circle containing a check mark, a gear, and a circle containing an x. +**Expectation**: Inline icons of "{spellexception}`octicon`" style are visible. They are a right arrow, a circle containing a check mark, a gear, and a circle containing an x. -MyST octicons: {octicon}`arrow-right`, {octicon}`check-circle`, {octicon}`gear`, {octicon}`x-circle` +MyST icons: {octicon}`arrow-right`, {octicon}`check-circle`, {octicon}`gear`, {octicon}`x-circle` ```{eval-rst} -reST octicons: :octicon:`arrow-right`, :octicon:`check-circle`, :octicon:`gear`, :octicon:`x-circle` +reST icons: :octicon:`arrow-right`, :octicon:`check-circle`, :octicon:`gear`, :octicon:`x-circle` ``` ### Additional diff --git a/docs/conf.py b/docs/conf.py index c470187b..5e115e33 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -192,6 +192,8 @@ "https://example.com", # SourceForge domains often block linkcheck r"https://.*\.sourceforge\.(net|io)/.*", + # Example broken link used in canary page + "https://documentation.ubuntu.com/sphinx-stack/a" ] # A regex list of URLs where anchors are ignored by 'make linkcheck' From edea2411effd9bf5a6c17870fa719ae1b6eaf794 Mon Sep 17 00:00:00 2001 From: Michael DuBelko Date: Fri, 17 Jul 2026 17:11:16 -0700 Subject: [PATCH 3/4] fix: make contributor listing work --- docs/_templates/footer.html | 4 ++-- docs/conf.py | 3 ++- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/_templates/footer.html b/docs/_templates/footer.html index e1d10889..7882d4ea 100644 --- a/docs/_templates/footer.html +++ b/docs/_templates/footer.html @@ -80,7 +80,7 @@ {%- endif %}
- {% if has_contributor_listing and display_contributors and pagename and page_source_suffix %} + {% if display_contributors and pagename and page_source_suffix %} {% set contributors = get_contributors_for_file(pagename, page_source_suffix) %} {% if contributors %} {% if contributors | length > 1 %} @@ -100,4 +100,4 @@ {% endif %}
Manage your tracker settings
-
\ No newline at end of file +
diff --git a/docs/conf.py b/docs/conf.py index 5e115e33..d6e7c9fc 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -78,6 +78,7 @@ "repo_default_branch": "main", # Docs location in the repo; used in links for viewing the source files "github_folder": "/docs/", + "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": "", @@ -299,4 +300,4 @@ intersphinx_mapping = { "sphinx-stack-docs": ("https://documentation.ubuntu.com/sphinx-stack/latest/", None), -} \ No newline at end of file +} From cdff04000a4e207822eca071d617845a5a6a2573 Mon Sep 17 00:00:00 2001 From: Michael DuBelko Date: Fri, 17 Jul 2026 17:30:20 -0700 Subject: [PATCH 4/4] fix: github_url path --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index d6e7c9fc..0f6b9e42 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -73,7 +73,7 @@ # documentation source files and creating GitHub issues are added at the bottom of # each page. # TODO: Change to your documentation GitHub repository URL or leave empty. - "github_url": "github.com/a-velasco/sphinx-stack-testing", + "github_url": "github.com/canonical/sphinx-stack", # Docs branch in the repo; used in links for viewing the source files "repo_default_branch": "main", # Docs location in the repo; used in links for viewing the source files