From 9080309e7cd8866350ebe7ca7f0692788be7d140 Mon Sep 17 00:00:00 2001 From: a-velasco Date: Tue, 7 Jul 2026 11:07:38 +0200 Subject: [PATCH 1/9] add verification for rerediraffe and reredirects extensions --- docs/canary-page.md | 6 ++++-- docs/conf.py | 6 ++++-- docs/index.rst | 2 +- docs/redirects.txt | 2 ++ 4 files changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/canary-page.md b/docs/canary-page.md index b77794d..da06abf 100644 --- a/docs/canary-page.md +++ b/docs/canary-page.md @@ -170,13 +170,15 @@ Article info directive to display a block of information about an article: :class-container: sd-p-2 sd-outline-muted ``` +(sphinx-rerediraffe)= ## `sphinx_rerediraffe` -(*Not applicable at the moment. Could publish this on RTD and add a redirect to `redirects.txt`*) +Appending `/test-rerediraffe` to the base URL of these docs should redirect to `/canary-page`. +(sphinx-reredirects)= ## `sphinx_reredirects` -(*Not applicable at the moment. Could publish this on RTD and add a redirect to `redirects.txt`*) +Appending `/test-reredirects` to the base URL of these docs should redirect to `/canary-page`. ## `sphinx_tabs.tabs` diff --git a/docs/conf.py b/docs/conf.py index e6b5ede..33a2b85 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -140,7 +140,7 @@ ################################ # html_static_path = ["_static"] -# templates_path = ["_templates"] +templates_path = ["_templates"] ############# # Redirects # @@ -157,6 +157,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 # @@ -246,7 +248,7 @@ ] # Excludes files from toctree -toc_filter_exclude = ["exclude", "hidden"] +toc_filter_exclude = ["exclude"] # Adds custom CSS files, located remotely or in 'html_static_path'. # html_css_files = [ diff --git a/docs/index.rst b/docs/index.rst index 5d4355f..05168c3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -47,4 +47,4 @@ Governance and policies :maxdepth: 1 Canary page - Hidden page <:hidden:hidden-page> \ No newline at end of file + Hidden page <:exclude:hidden-page> \ No newline at end of file diff --git a/docs/redirects.txt b/docs/redirects.txt index cf8ae22..f295e7c 100644 --- a/docs/redirects.txt +++ b/docs/redirects.txt @@ -6,3 +6,5 @@ # 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 89fbbeaf11b4f0f52b3ff97e352dad90e38596f8 Mon Sep 17 00:00:00 2001 From: a-velasco Date: Tue, 7 Jul 2026 18:05:51 +0200 Subject: [PATCH 2/9] add some more descriptions --- docs/canary-page.md | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/docs/canary-page.md b/docs/canary-page.md index da06abf..3cfdd3b 100644 --- a/docs/canary-page.md +++ b/docs/canary-page.md @@ -12,7 +12,7 @@ These are the default extensions bundled into `canonical_sphinx`. ### Furo theme -(*N/A?*) +(*N/A*) ### MyST parser @@ -213,11 +213,21 @@ This card is inside a tab ## `sphinxcontrib.jquery` -(*N/A?*) +(*N/A? Maybe test this through another extension that depends on jquery?*) ## `sphinxext.opengraph` -(*N/A?*) +The HTML source for this page should include the following meta tags: + +```html + + + + + + + +``` ## `sphinx_config_options` @@ -238,7 +248,7 @@ Config options can also be cross-referenced: {config:option}`cache.enabled`. ## `sphinx_contributor_listing` -(*Troubleshooting: Configured conf.py and footer, but contributors are not displayed*) +(*Needs troubleshooting: Configured conf.py and footer, but contributors are not displayed*) @@ -248,14 +258,12 @@ Config options can also be cross-referenced: {config:option}`cache.enabled`. ## `sphinx_llm.txt` - +(*Find markdown artifacts?*) ## `sphinx_related_links` See "Related link" on the right side of the page, below the contents. - - ## `sphinx_roles` This is a {literalref}`literal reference `. @@ -327,4 +335,4 @@ It should go to `https://documentation.ubuntu.com/sphinx-stack/latest/how-to/opt ## `sphinx_sitemap` -(*N/A?*) \ No newline at end of file +Appending `/sitemap.xml` to the base URL of this documentation should display an XML file listing all pages. \ No newline at end of file From 6561f52e9a8f394f8a4d921daed563523369d6d2 Mon Sep 17 00:00:00 2001 From: a-velasco Date: Tue, 7 Jul 2026 18:24:23 +0200 Subject: [PATCH 3/9] add description to notfound.extension --- docs/canary-page.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/canary-page.md b/docs/canary-page.md index 3cfdd3b..fd4d871 100644 --- a/docs/canary-page.md +++ b/docs/canary-page.md @@ -24,9 +24,9 @@ These are the default extensions bundled into `canonical_sphinx`. ## `notfound.extension` -(*N/A?*) +Try to access this page, but introduce a typo in the URL. - +The page should render 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` From 18f11d6722da7eb98ad706dae38a67b7fbff6f6c Mon Sep 17 00:00:00 2001 From: a-velasco Date: Tue, 7 Jul 2026 18:25:12 +0200 Subject: [PATCH 4/9] remove unused tags --- docs/canary-page.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/canary-page.md b/docs/canary-page.md index fd4d871..38cc386 100644 --- a/docs/canary-page.md +++ b/docs/canary-page.md @@ -170,12 +170,10 @@ Article info directive to display a block of information about an article: :class-container: sd-p-2 sd-outline-muted ``` -(sphinx-rerediraffe)= ## `sphinx_rerediraffe` Appending `/test-rerediraffe` to the base URL of these docs should redirect to `/canary-page`. -(sphinx-reredirects)= ## `sphinx_reredirects` Appending `/test-reredirects` to the base URL of these docs should redirect to `/canary-page`. From 7204a51f91364654358e2192a357c4c0a29544ab Mon Sep 17 00:00:00 2001 From: a-velasco Date: Tue, 7 Jul 2026 18:28:20 +0200 Subject: [PATCH 5/9] fix github repo url --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index ab71aab..18e366f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -72,7 +72,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/avgomes/sphinx-stack-testing", + "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 From 3d2a7597969e6406ae4cdb9d7073fabb34de19e7 Mon Sep 17 00:00:00 2001 From: a-velasco Date: Tue, 7 Jul 2026 18:42:53 +0200 Subject: [PATCH 6/9] add missing hidden-page after rebase --- docs/hidden-page.md | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 docs/hidden-page.md diff --git a/docs/hidden-page.md b/docs/hidden-page.md new file mode 100644 index 0000000..471a544 --- /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 From a362ef49c8923b675f792b284e45dcddaf458ba2 Mon Sep 17 00:00:00 2001 From: a-velasco Date: Tue, 7 Jul 2026 19:42:45 +0200 Subject: [PATCH 7/9] add reST versions of structures --- docs/canary-page.md | 369 +++++++++++++++++++++++++++++++++++--------- 1 file changed, 300 insertions(+), 69 deletions(-) diff --git a/docs/canary-page.md b/docs/canary-page.md index 38cc386..3418126 100644 --- a/docs/canary-page.md +++ b/docs/canary-page.md @@ -40,126 +40,245 @@ The following grid has an outer outline and three grid items: :outline: ```{grid-item} -Grid item 1 +MyST grid item 1 ``` ```{grid-item} -Grid item 2 +MyST grid item 2 ``` ```{grid-item} -Grid item 3 +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 +``` + The following grid is composed of cards: ````{grid} ```{grid-item-card} Title 1 -Grid item card 1 +MyST grid item card 1 ``` ```{grid-item-card} Title 2 -Grid item card 2 +MyST grid item card 2 ``` ```{grid-item-card} Title 3 -Grid item card 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 +``` + ### Cards -```{card} Card title +```{card} MyST card title Card content ``` +```{eval-rst} +.. card:: reST card title + + Card content +``` + The following card had header and footer text: -```{card} Card title -Header text +```{card} MyST card title +Header ^^^ Card content +++ -Footer text +Footer +``` + +```{eval-rst} +.. card:: reST card title + + Header + ^^^ + Card content + +++ + Footer ``` ```{card} Click me :link: https://documentation.ubuntu.com/sphinx-stack/latest/ -This card links to `https://documentation.ubuntu.com/sphinx-stack/latest/` +This MyST card links to `https://documentation.ubuntu.com/sphinx-stack/latest/` +``` + +```{eval-rst} +.. card:: Click me + :link: https://documentation.ubuntu.com/sphinx-stack/latest/ + + This reST card links to ``https://documentation.ubuntu.com/sphinx-stack/latest/`` ``` ### Dropdowns The following dropdown is set to open by default. -```{dropdown} Dropdown title +```{dropdown} MyST dropdown title :open: Dropdown content ``` +```{eval-rst} +.. dropdown:: reST dropdown title + :open: + + Dropdown content +``` + The following dropdown is closed by default, has a grey title card, and a wrench icon. -```{dropdown} Dropdown title +```{dropdown} MyST dropdown title :icon: tools :color: secondary Dropdown content ``` +```{eval-rst} +.. dropdown:: reST dropdown title + :icon: tools + :color: secondary + + Dropdown content +``` + ### Tabs -The following tab set synchronizes with the next tab set: +The following MyST tab sets synchronize with each other: ````{tab-set} -```{tab-item} Label 1 -:sync: label1 +```{tab-item} MyST label 1 +:sync: myst-label-1 -Content 1 +MyST tab content 1 ``` -```{tab-item} Label 2 -:sync: label2 +```{tab-item} MyST label 2 +:sync: myst-label-2 -Content 2 +MyST tab content 2 ``` ```` -The following tab set synchronizes with the previous, and nests other elements inside: - `````{tab-set} -````{tab-item} Label 1 -:sync: label1 +````{tab-item} MyST label 1 +:sync: myst-label-1 -This tab includes a code block: +This MyST tab includes a code block: ```{code-block} python print("hello") ``` ```` -````{tab-item} Label 2 -:sync: label2 +````{tab-item} MyST label 2 +:sync: myst-label-2 ```{card} -This card is inside a tab +This MyST card is inside a MyST tab. ``` ```` ````` +```{eval-rst} +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 -Plain inline badges: -{bdg-info}`info`, {bdg-info-line}`info-line` +Plain inline MyST badges: {bdg-info}`info`, {bdg-info-line}`info-line` +```{eval-rst} +Plain inline reST badges: :bdg-info:`info`, :bdg-info-line:`info-line` +``` -Clickable inline badges: -{bdg-link-info}`https://example.com`, {bdg-link-info-line}`https://example.com` +--- + +Clickable inline MyST badges: {bdg-link-info}`https://example.com`, {bdg-link-info-line}`https://example.com` +```{eval-rst} +Clickable inline reST badges: :bdg-link-info:`https://example.com`, :bdg-link-info-line:`https://example.com` +``` + +--- + +Clickable MyST button: -Clickable button: ```{button-link} https://example.com :color: info ``` +```{eval-rst} +Clickable reST button: + +.. button-link:: https://example.com + :color: info +``` -Inline octicons: {octicon}`arrow-right`, {octicon}`check-circle`, {octicon}`gear`, {octicon}`x-circle` +--- + +Inline MyST octicons: {octicon}`arrow-right`, {octicon}`check-circle`, {octicon}`gear`, {octicon}`x-circle` +```{eval-rst} +Inline reST octicons: :octicon:`arrow-right`, :octicon:`check-circle`, :octicon:`gear`, :octicon:`x-circle` +``` ### Additional -Article info directive to display a block of information about an article: +MyST article info directive to display a block of information about an article: ```{article-info} :avatar-link: https://executablebooks.org/ @@ -170,6 +289,19 @@ Article info directive to display a block of information about an article: :class-container: sd-p-2 sd-outline-muted ``` +reST article info directive to display a block of information about an article: + +```{eval-rst} + +.. article-info:: + :avatar-link: https://executablebooks.org/ + :avatar-outline: muted + :author: Executable Books + :date: Jul 24, 2021 + :read-time: 5 min read + :class-container: sd-p-2 sd-outline-muted +``` + ## `sphinx_rerediraffe` Appending `/test-rerediraffe` to the base URL of these docs should redirect to `/canary-page`. @@ -180,38 +312,64 @@ Appending `/test-reredirects` to the base URL of these docs should redirect to ` ## `sphinx_tabs.tabs` -The following tab set synchronizes with the next tab set: +The following MyST tab sets synchronize with each other: ````{tabs} -```{group-tab} Label 1 -Content 1 +```{group-tab} MyST label 1 +MyST tab content 1 ``` -```{group-tab} Label 2 -Content 2 +```{group-tab} MyST label 2 +MyST tab content 2 ``` ```` -The following tab set synchronizes with the previous, and nests other elements inside: - `````{tabs} -````{group-tab} Label 1 +````{group-tab} MyST label 1 -This tab includes a code block: +This MyST tab includes a code block: ```{code-block} python print("hello") ``` ```` -````{group-tab} Label 2 +````{group-tab} MyST label 2 ```{card} -This card is inside a tab +This MyST card is inside a MyST tab. ``` ```` ````` +```{eval-rst} +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. +``` + ## `sphinxcontrib.jquery` -(*N/A? Maybe test this through another extension that depends on jquery?*) +N/A ## `sphinxext.opengraph` @@ -229,9 +387,9 @@ The HTML source for this page should include the following meta tags: ## `sphinx_config_options` -Example config option structure: +Example config option structure in MyST: -```{config:option} cache.enabled +```{config:option} cache.enabled.myst :shortdesc: Enable or disable caching :type: boolean :default: false @@ -242,13 +400,27 @@ Example config option structure: Controls whether the application uses caching to improve performance. ``` -Config options can also be cross-referenced: {config:option}`cache.enabled`. +Config options can also be cross-referenced: {config:option}`cache.enabled.myst`. -## `sphinx_contributor_listing` +Example config option structure in reST: -(*Needs troubleshooting: Configured conf.py and footer, but contributors are not displayed*) +```{eval-rst} +.. config:option:: cache.enabled.rest + :shortdesc: Enable or disable caching + :type: boolean + :default: false + :scope: server + :liveupdate: true + :condition: Only available with premium license - + Controls whether the application uses caching to improve performance. + +Config options can also be cross-referenced: :config:option:`cache.enabled.rest`. +``` + +## `sphinx_contributor_listing` + +Contributor list should be displayed in the footer of the page. ## `sphinx_filtered_toctree` @@ -256,7 +428,7 @@ Config options can also be cross-referenced: {config:option}`cache.enabled`. ## `sphinx_llm.txt` -(*Find markdown artifacts?*) +N/A ## `sphinx_related_links` @@ -264,13 +436,26 @@ See "Related link" on the right side of the page, below the contents. ## `sphinx_roles` -This is a {literalref}`literal reference `. +This is a {literalref}`literal reference in MyST `. + +```{eval-rst} +This is a :literalref:`literal reference in reST `. +``` -The words "{spellexception}`Lorem ipsum`" should be excluded from the spell checker. +The words "{spellexception}`Lorem ipsum`" should be excluded from the spell checker (MyST directive). -The line of text below should not be visible: +```{eval-rst} +The words ":spellexception:`Lorem ipsum`" should be excluded from the spell checker (reST directive). +``` + +The line of text below should not be visible (MyST directive): {none}`If you can see this text, you might have an issue with the sphinx_roles extension.` +```{eval-rst} +The line of text below should not be visible (reST directive): +:none:`If you can see this text, you might have an issue with the sphinx_roles extension.` +``` + ## `sphinx_terminal` `user@pc` runs the command `echo 'hello'` in `~/path`. The output is `hello`. @@ -283,53 +468,99 @@ The input command `echo 'hello'` can be copied with the copy button on the top r :host: pc :dir: ~/path -echo 'hello' +echo 'hello MyST' -hello +hello MyST ``` -The terminal below shows only the output `hello`: +
+ +```{eval-rst} +.. terminal:: + :copy: + :user: user + :host: pc + :dir: ~/path + + echo 'hello reST' + + hello reST +``` + +The terminal below shows only the output: ```{terminal} :output-only: -hello +hello MyST +``` + +
+ +```{eval-rst} +.. terminal:: + :output-only: + + hello reST ``` ## `sphinx_ubuntu_images` -Below is an auto-generated list of all Ubuntu images for Resolute Raccoon (26.04): +Below is an auto-generated list of all Ubuntu images for 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 ``` -There should be a "Watch on YouTube" button with an orange play icon to the right of this text. +There should be a "Watch on YouTube" button with an orange play icon to the right of this paragraph. This first one is generated with MyST. -All text in this section is written below the `youtube` directive, and should therefore render to the left of the button, wrapping around it. +All text in this section is written below the ```{youtube} MyST directive, and should therefore render to the left of the button, wrapping around it. + +After the button, the rest of the text will go back to taking up the full horizontal length of the section. + +```{eval-rst} +.. youtube:: https://www.youtube.com/watch?v=dQw4w9WgXcQ +``` + +There should be another "Watch on YouTube" button with an orange play icon to the right of this paragraph. This second one was generated with reST. + +All text in this section is written below the `.. youtube::` reST directive, and should therefore render to the left of the button, wrapping around it. After the button, the rest of the text will go back to taking up the full horizontal length of the section. ## `sphinxcontrib.cairosvgconverter` -(*N/A?*) +N/A ## `sphinx_last_updated_by_git` -Check footer of the page for text that says "Last updated on" and a date. +Check footer of the page for text that says "Last updated on", followed by a date. ## `sphinx.ext.intersphinx` -Below is a link to the intersphinx guide in the official Sphinx Stack docs: +Below are two identical references to the intersphinx guide in the official Sphinx Stack docs: + +MyST reference: {ref}`sphinx-stack-docs:how-to-link-docs-intersphinx` -{ref}`sphinx-stack-docs:how-to-link-docs-intersphinx` +```{eval-rst} +reST reference :ref:`sphinx-stack-docs:how-to-link-docs-intersphinx` +``` -It should go to `https://documentation.ubuntu.com/sphinx-stack/latest/how-to/optional-customisation/external-referencing-intersphinx/` +Both 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/). ## `sphinx_sitemap` From 6523a7d31512037a068c729a92ad94df95332394 Mon Sep 17 00:00:00 2001 From: Andreia Velasco Date: Fri, 17 Jul 2026 11:47:21 +0200 Subject: [PATCH 8/9] address review comments --- docs/_templates/footer.html | 2 +- docs/canary-page.md | 82 +++++++++++++++++++++++++------------ docs/conf.py | 2 +- 3 files changed, 57 insertions(+), 29 deletions(-) diff --git a/docs/_templates/footer.html b/docs/_templates/footer.html index e1d1088..ffd301d 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 %} diff --git a/docs/canary-page.md b/docs/canary-page.md index 3418126..1fce30b 100644 --- a/docs/canary-page.md +++ b/docs/canary-page.md @@ -1,5 +1,6 @@ --- relatedlinks: "[Related link](https://example.com)" +hide-toc: true --- # Test page for default extensions @@ -12,25 +13,42 @@ These are the default extensions bundled into `canonical_sphinx`. ### Furo theme -(*N/A*) +This is 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. + +**Expectation**: The HTML of this page does **not** contain the following `
` classes: + +* `toc-title-container` +* `toc-tree-container` ### MyST parser -(*Use [Typography verification page](https://documentation.ubuntu.com/ulwazi/content/typography-verification/) from Ulwazi?*) +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 -(*N/A?*) +This is tested by writing a URL and checking that it turns into a link. + +**Expectation**: //localhost is a clickable link. + +**Expectation**: The HTML of this page contains + +```html +//localhost +``` ## `notfound.extension` -Try to access this page, but introduce a typo in the URL. +This is tested by accessing a non-existent sub-page of this docset. -The page should render a "Page not found" message with the same CSS styling as the rest of the documentation, maintaining the left-side navigation and upper menu. +**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` -Sample structures are based on [`sphinx-design` documentation examples](https://sphinx-design.readthedocs.io/en/latest/index.html). +This is tested by rendering sample structures based on [`sphinx-design` documentation examples](https://sphinx-design.readthedocs.io/en/latest/index.html). ### Grids @@ -304,11 +322,11 @@ reST article info directive to display a block of information about an article: ## `sphinx_rerediraffe` -Appending `/test-rerediraffe` to the base URL of these docs should redirect to `/canary-page`. +**Expectation**: https://documentation.ubuntu.com/sphinx-stack/test-rerediraffe redirects to `/canary-page`. ## `sphinx_reredirects` -Appending `/test-reredirects` to the base URL of these docs should redirect to `/canary-page`. +**Expectation**: https://documentation.ubuntu.com/sphinx-stack/test-reredirects redirects to `/canary-page`. ## `sphinx_tabs.tabs` @@ -367,10 +385,6 @@ The following reST tab sets synchronize with each other: This reST card is inside a reST tab. ``` -## `sphinxcontrib.jquery` - -N/A - ## `sphinxext.opengraph` The HTML source for this page should include the following meta tags: @@ -420,39 +434,57 @@ Config options can also be cross-referenced: :config:option:`cache.enabled.rest` ## `sphinx_contributor_listing` -Contributor list should be displayed in the footer of the page. +**Expectation**: Contributor list should be displayed in the footer of the page. + +**Expectation**: The HTML of this page should contain + +```html + +``` ## `sphinx_filtered_toctree` -{ref}`hidden-page` is below this page, but excluded from the 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`. + +**Expectation**: The HTML of this page should **not** contain + +```html +Canary page +``` ## `sphinx_llm.txt` -N/A +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` -See "Related link" on the right side of the page, below the contents. +This is tested by adding `relatedlinks` to this page's metadata. + +**Expectation**: "Related links" can be seen on the right side of this page. ## `sphinx_roles` -This is a {literalref}`literal reference in MyST `. +**Expectation**: This is a {literalref}`literal reference in MyST `. ```{eval-rst} -This is a :literalref:`literal reference in reST `. +**Expectation**: This is a :literalref:`literal reference in reST `. ``` -The words "{spellexception}`Lorem ipsum`" should be excluded from the spell checker (MyST directive). +**Expectation**: The words "{spellexception}`Lorem ipsum`" should be excluded from the spell checker (MyST directive). ```{eval-rst} -The words ":spellexception:`Lorem ipsum`" should be excluded from the spell checker (reST directive). +**Expectation**: The words ":spellexception:`Lorem ipsum`" should be excluded from the spell checker (reST directive). ``` -The line of text below should not be visible (MyST directive): +**Expectation**: The line of text below, starting with "If you can see this text...", should **not** be visible (MyST directive): {none}`If you can see this text, you might have an issue with the sphinx_roles extension.` ```{eval-rst} -The line of text below should not be visible (reST directive): +**Expectation**: The line of text below, starting with "If you can see this text...", should **not** be visible (reST directive): :none:`If you can see this text, you might have an issue with the sphinx_roles extension.` ``` @@ -542,10 +574,6 @@ All text in this section is written below the `.. youtube::` reST directive, and After the button, the rest of the text will go back to taking up the full horizontal length of the section. -## `sphinxcontrib.cairosvgconverter` - -N/A - ## `sphinx_last_updated_by_git` Check footer of the page for text that says "Last updated on", followed by a date. @@ -564,4 +592,4 @@ Both should link to [documentation.ubuntu.com/sphinx-stack/latest/how-to/optiona ## `sphinx_sitemap` -Appending `/sitemap.xml` to the base URL of this documentation should display an XML file listing all pages. \ No newline at end of file +**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 18e366f..d22197f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -76,7 +76,7 @@ # 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": "", From 0a854dbab0c76bf4c65750f91d5c4c37a7781554 Mon Sep 17 00:00:00 2001 From: Andreia Velasco Date: Fri, 17 Jul 2026 14:56:53 +0200 Subject: [PATCH 9/9] additional polishing and html checks --- docs/canary-page.md | 253 ++++++++++++++++++++++++++++++-------------- docs/conf.py | 1 + 2 files changed, 177 insertions(+), 77 deletions(-) diff --git a/docs/canary-page.md b/docs/canary-page.md index 1fce30b..33f8056 100644 --- a/docs/canary-page.md +++ b/docs/canary-page.md @@ -1,5 +1,5 @@ --- -relatedlinks: "[Related link](https://example.com)" +relatedlinks: "[Example link](https://example.com)" hide-toc: true --- @@ -9,18 +9,22 @@ This page contains basic example structures from every MyST and rST extension th ## `canonical_sphinx` -These are the default extensions bundled into `canonical_sphinx`. +Below are the default extensions bundled into `canonical_sphinx`. ### Furo theme -This is tested by setting Furo's `hide-toc` feature to `true` in this page's metadata. +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. -**Expectation**: The HTML of this page does **not** contain the following `
` classes: +**HTML check**: The HTML of this page does **not** contain the following `
` classes: -* `toc-title-container` -* `toc-tree-container` +```html +
+ (...) +
+ (...) +``` ### MyST parser @@ -30,11 +34,11 @@ This is tested with the `{sub-ref}` MyST directive to count words through `wordc ### linkify-it-py -This is tested by writing a URL and checking that it turns into a link. +This is tested by writing a URL in plain text and checking that it turns into a link. **Expectation**: //localhost is a clickable link. -**Expectation**: The HTML of this page contains +**HTML check**: ```html //localhost @@ -42,7 +46,7 @@ This is tested by writing a URL and checking that it turns into a link. ## `notfound.extension` -This is tested by accessing a non-existent sub-page of this docset. +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. @@ -52,7 +56,9 @@ This is tested by rendering sample structures based on [`sphinx-design` document ### Grids -The following grid has an outer outline and three grid items: +#### Basic grid + +**Expectation**: The following grids have an outer outline and three grid items. ````{grid} :outline: @@ -82,7 +88,16 @@ MyST grid item 3 reST grid item 3 ``` -The following grid is composed of cards: +**HTML check**: + +```html +
+ (...) +``` + +#### Card grids + +**Expectation**: The following grids are composed of cards. ````{grid} ```{grid-item-card} Title 1 @@ -112,8 +127,17 @@ MyST grid item card 3 reST grid item card 3 ``` +**HTML check**: + +```html +
+ (...) +``` + ### Cards +#### Basic card + ```{card} MyST card title Card content ``` @@ -124,7 +148,16 @@ Card content Card content ``` -The following card had header and footer text: +**HTML check**: + +```html +
+ (...) +``` + +#### Card with header and footer + +**Expectation**: The following cards have header and footer text. ```{card} MyST card title Header @@ -144,22 +177,43 @@ Footer 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/latest/ +:link: https://documentation.ubuntu.com/sphinx-stack/ -This MyST card links to `https://documentation.ubuntu.com/sphinx-stack/latest/` +This MyST card links to `https://documentation.ubuntu.com/sphinx-stack/` ``` ```{eval-rst} .. card:: Click me - :link: https://documentation.ubuntu.com/sphinx-stack/latest/ + :link: https://documentation.ubuntu.com/sphinx-stack/ - This reST card links to ``https://documentation.ubuntu.com/sphinx-stack/latest/`` + This reST card links to ``https://documentation.ubuntu.com/sphinx-stack/`` ``` +**HTML check**: + +```html + + https://documentation.ubuntu.com/sphinx-stack/latest/ + +``` ### Dropdowns -The following dropdown is set to open by default. +#### Basic dropdown + +**Expectation**: The dropdowns are open by default. ```{dropdown} MyST dropdown title :open: @@ -174,7 +228,16 @@ Dropdown content Dropdown content ``` -The following dropdown is closed by default, has a grey title card, and a wrench icon. +**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 @@ -191,9 +254,18 @@ Dropdown content Dropdown content ``` +**HTML check**: + +```html + + (...) + + (...) +``` + ### Tabs -The following MyST tab sets synchronize with each other: +**Expectation**: The following MyST tab sets synchronize with each other: ````{tab-set} ```{tab-item} MyST label 1 @@ -227,7 +299,7 @@ This MyST card is inside a MyST tab. ````` ```{eval-rst} -The following reST tab sets synchronize with each other: +**Expectation**: The following reST tab sets synchronize with each other: .. tab-set:: @@ -261,60 +333,68 @@ The following reST tab sets synchronize with each other: ### Badges, Buttons and Icons -Plain inline MyST badges: {bdg-info}`info`, {bdg-info-line}`info-line` +#### 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} -Plain inline reST badges: :bdg-info:`info`, :bdg-info-line:`info-line` +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. -Clickable inline MyST badges: {bdg-link-info}`https://example.com`, {bdg-link-info-line}`https://example.com` +MyST badges: {bdg-link-info}`https://example.com`, {bdg-link-info-line}`https://example.com` ```{eval-rst} -Clickable inline reST badges: :bdg-link-info:`https://example.com`, :bdg-link-info-line:`https://example.com` +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: -Clickable MyST button: +MyST button: ```{button-link} https://example.com :color: info ``` ```{eval-rst} -Clickable reST button: +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. -Inline MyST octicons: {octicon}`arrow-right`, {octicon}`check-circle`, {octicon}`gear`, {octicon}`x-circle` +MyST octicons: {octicon}`arrow-right`, {octicon}`check-circle`, {octicon}`gear`, {octicon}`x-circle` ```{eval-rst} -Inline reST octicons: :octicon:`arrow-right`, :octicon:`check-circle`, :octicon:`gear`, :octicon:`x-circle` +reST octicons: :octicon:`arrow-right`, :octicon:`check-circle`, :octicon:`gear`, :octicon:`x-circle` ``` ### Additional -MyST article info directive to display a block of information about an article: +**Expectation**: A block of information about an article is displayed. It shows an avatar, author, date, and read duration: ```{article-info} -:avatar-link: https://executablebooks.org/ +:avatar: https://assets.ubuntu.com/v1/cc828679-docs_illustration.svg :avatar-outline: muted -:author: Executable Books +:author: MyST author :date: Jul 24, 2021 :read-time: 5 min read :class-container: sd-p-2 sd-outline-muted ``` -reST article info directive to display a block of information about an article: - ```{eval-rst} .. article-info:: - :avatar-link: https://executablebooks.org/ + :avatar: https://assets.ubuntu.com/v1/cc828679-docs_illustration.svg :avatar-outline: muted - :author: Executable Books + :author: reST author :date: Jul 24, 2021 :read-time: 5 min read :class-container: sd-p-2 sd-outline-muted @@ -322,15 +402,27 @@ reST article info directive to display a block of information about an article: ## `sphinx_rerediraffe` -**Expectation**: https://documentation.ubuntu.com/sphinx-stack/test-rerediraffe redirects to `/canary-page`. +**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**: https://documentation.ubuntu.com/sphinx-stack/test-reredirects redirects to `/canary-page`. +**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` -The following MyST tab sets synchronize with each other: +**Expectation**: The following MyST tab sets synchronize with each other: ````{tabs} ```{group-tab} MyST label 1 @@ -358,7 +450,7 @@ This MyST card is inside a MyST tab. ````` ```{eval-rst} -The following reST tab sets synchronize with each other: +**Expectation**: The following reST tab sets synchronize with each other: .. tabs:: .. group-tab:: reST label 1 @@ -387,7 +479,7 @@ The following reST tab sets synchronize with each other: ## `sphinxext.opengraph` -The HTML source for this page should include the following meta tags: +**HTML check**: The HTML source of this page should include the following meta tags: ```html @@ -401,10 +493,10 @@ The HTML source for this page should include the following meta tags: ## `sphinx_config_options` -Example config option structure in MyST: +**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 +:shortdesc: Enable or disable caching (MyST) :type: boolean :default: false :scope: server @@ -414,13 +506,11 @@ Example config option structure in MyST: Controls whether the application uses caching to improve performance. ``` -Config options can also be cross-referenced: {config:option}`cache.enabled.myst`. - -Example config option structure in reST: +**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 + :shortdesc: Enable or disable caching (reST) :type: boolean :default: false :scope: server @@ -429,14 +519,14 @@ Example config option structure in reST: Controls whether the application uses caching to improve performance. -Config options can also be cross-referenced: :config:option:`cache.enabled.rest`. +**Expectation**: :config:option:`cache.enabled.rest` should link to the reST config block. ``` ## `sphinx_contributor_listing` -**Expectation**: Contributor list should be displayed in the footer of the page. +**Expectation**: The footer of this page should contain clickable text starting with "Thanks to". Clicking it should display a pop-up list of contributors. -**Expectation**: The HTML of this page should contain +**HTML check**: ```html @@ -448,10 +538,10 @@ This is tested by creating the page {ref}`hidden-page` as a sibling of this curr **Expectation**: The left-side TOC should **not** visibly contain a page called {ref}`hidden-page`. -**Expectation**: The HTML of this page should **not** contain +**HTML check**: The HTML of this page should **not** contain ```html -Canary page +Hidden page ``` ## `sphinx_llm.txt` @@ -462,35 +552,40 @@ This is tested by appending `llms-full.txt` to the site root. ## `sphinx_related_links` -This is tested by adding `relatedlinks` to this page's metadata. +This is tested by adding `relatedlinks` to this page's metadata with an example link. -**Expectation**: "Related links" can be seen on the right side of this page. +**Expectation**: A "Related links" list can be seen on the right side of this page and contains an example link. ## `sphinx_roles` -**Expectation**: This is a {literalref}`literal reference in MyST `. +**Expectation**: The following literal references are links to example.com. + +This is a {literalref}`literal reference in MyST `. ```{eval-rst} -**Expectation**: This is a :literalref:`literal reference in reST `. +This is a :literalref:`literal reference in reST `. ``` -**Expectation**: The words "{spellexception}`Lorem ipsum`" should be excluded from the spell checker (MyST directive). +**Expectation**: + +"{spellexception}`Lorem ipsum`" should be excluded from the spell checker (MyST directive). ```{eval-rst} -**Expectation**: The words ":spellexception:`Lorem ipsum`" should be excluded from the spell checker (reST directive). +":spellexception:`Lorem ipsum`" should be excluded from the spell checker (reST directive). ``` -**Expectation**: The line of text below, starting with "If you can see this text...", should **not** be visible (MyST directive): -{none}`If you can see this text, you might have an issue with the sphinx_roles extension.` +**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} -**Expectation**: The line of text below, starting with "If you can see this text...", should **not** be visible (reST directive): -:none:`If you can see this text, you might have an issue with the sphinx_roles extension.` +Phrase hidden by reST directive: :none:`If you can see this text, you might have an issue with the sphinx_roles extension.` ``` ## `sphinx_terminal` -`user@pc` runs the command `echo 'hello'` in `~/path`. The output is `hello`. +**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: @@ -519,7 +614,7 @@ hello MyST hello reST ``` -The terminal below shows only the output: +**Expectation**: The terminals below only show the output: ```{terminal} :output-only: @@ -538,7 +633,7 @@ hello MyST ## `sphinx_ubuntu_images` -Below is an auto-generated list of all Ubuntu images for Resolute Raccoon. +**Expectation**: Lists of images for Ubuntu 26.04 LTS (Resolute Raccoon). MyST directive output: @@ -558,29 +653,35 @@ reST directive output: ```{youtube} https://www.youtube.com/watch?v=dQw4w9WgXcQ ``` -There should be a "Watch on YouTube" button with an orange play icon to the right of this paragraph. This first one is generated with MyST. +**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. -All text in this section is written below the ```{youtube} MyST directive, and should therefore render to the left of the button, wrapping around it. +This text is written below the ```{youtube} MyST directive. Therefore it should render to the left of the button and wrap around it. -After the button, the rest of the text will go back to taking up the full horizontal length of the section. +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 ``` -There should be another "Watch on YouTube" button with an orange play icon to the right of this paragraph. This second one was generated with reST. +**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. -All text in this section is written below the `.. youtube::` reST directive, and should therefore render to the left of the button, wrapping around it. +This text is written below the `.. youtube::` reST directive. Therefore it should render to the left of the button and wrap around it. -After the button, the rest of the text will go back to taking up the full horizontal length of the section. +Text below the button should expand back into taking up the full horizontal length of the section. ## `sphinx_last_updated_by_git` -Check footer of the page for text that says "Last updated on", followed by a date. +**Expectation**: The page footer should contain text that says "Last updated on", followed by a date. + +**HTML check**: + +```html + +``` ## `sphinx.ext.intersphinx` -Below are two identical references to the intersphinx guide in the official Sphinx Stack docs: +**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` @@ -588,8 +689,6 @@ MyST reference: {ref}`sphinx-stack-docs:how-to-link-docs-intersphinx` reST reference :ref:`sphinx-stack-docs:how-to-link-docs-intersphinx` ``` -Both 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/). - ## `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 d22197f..c470187 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