Add Sphinx examples, align doc requirements with main documentation (#…

…6011)
plone · May 14, 2024 · 96eb4fa · 96eb4fa
1 parent 3aa82cf
commit 96eb4fa
Show file tree

Hide file tree

Showing 5 changed files with 11 additions and 9 deletions.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -62,6 +62,7 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
     "sphinx_copybutton",
+    "sphinx_examples",
     "sphinxext.opengraph",
     "sphinxcontrib.video",
 ]

diff --git a/docs/source/contributing/documentation.md b/docs/source/contributing/documentation.md
@@ -155,6 +155,8 @@ To hyperlink to Storybook entries from the narrative documentation, you can use
 Use HTML syntax to enable hyperlinking in development, within Netlify preview builds, and when the main Plone documenation is updated.
 Hyperlinking in development requires that you run both `make docs-html` and `make storybook-build` commands once, then whenever you update either the narrative documentation or the Storybook.
 
+% sphinx-examples does not render HTML
+
 ```html
 <a href="/storybook/index.html?path=/story/edit-widgets-colorpicker--default">color picker widget</a>
 ```
@@ -163,8 +165,6 @@ Hyperlinking in development requires that you run both `make docs-html` and `mak
 
 Use CommonMark syntax to point only to the main production Plone documentation.
 
-```md
+```{example}
 [color picker widget](https://6.docs.plone.org/storybook/index.html?path=/story/edit-widgets-colorpicker--default)
 ```
-
-[color picker widget](https://6.docs.plone.org/storybook/index.html?path=/story/edit-widgets-colorpicker--default)
diff --git a/docs/source/upgrade-guide/index.md b/docs/source/upgrade-guide/index.md
@@ -60,7 +60,7 @@ Then update the version of `@plone/scripts` to at least version `3.6.1`.
 The following example shows the minimum valid versions to use under the `dependencies` key.
 
 ```json
-dependencies: {
+"dependencies": {
   "@plone/volto": "18.0.0-alpha.21",
   "@plone/scripts": "^3.6.1"
 }

diff --git a/packages/volto/news/6011.documentation b/packages/volto/news/6011.documentation
@@ -0,0 +1 @@
+Add sphinx-examples extension, update examples, align docs requirements with main documentation, and fix JSON example in upgrade guide. @stevepiercy
diff --git a/requirements-docs.txt b/requirements-docs.txt
@@ -2,19 +2,19 @@ docutils<0.17,>=0.15  # sphinx-book-theme 0.2.0 has requirement docutils<0.17,>=
 Sphinx<5,>=3  # sphinx-book-theme 0.3.3 has requirement sphinx<5,>=3
 lesscpy
 linkify-it-py
-myst-parser==1.0.0  # Temporary pin until theme is updated.
+myst-parser
+pydata-sphinx-theme<=0.8.99  # Build fails in 0.9.0. See https://github.com/plone/documentation/issues/1297
 sphinx-autobuild
-pydata-sphinx-theme<=0.8.99
-sphinx-book-theme==0.3.3
+sphinx-book-theme==0.3.3  # Temporary pin until we can sort out HTML refactoring.
 sphinx-copybutton
+sphinx-examples
 sphinx-sitemap
 sphinx-togglebutton
-sphinxcontrib-spelling
-sphinxext-opengraph
 sphinxcontrib-applehelp==1.0.4  # https://github.com/plone/documentation/issues/1604
 sphinxcontrib-devhelp==1.0.2  # https://github.com/plone/documentation/issues/1604
 sphinxcontrib-htmlhelp==2.0.1  # https://github.com/plone/documentation/issues/1604
 sphinxcontrib-qthelp==1.0.3  # https://github.com/plone/documentation/issues/1604
 sphinxcontrib-serializinghtml==1.1.5  # https://github.com/plone/documentation/issues/1604
 sphinxcontrib-video
+sphinxext-opengraph
 vale==2.30.0