From 96eb4fa4c0a1cb28e89f8f6e457978f748cc5112 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 14 May 2024 02:33:20 -0700 Subject: [PATCH] Add Sphinx examples, align doc requirements with main documentation (#6011) --- docs/source/conf.py | 1 + docs/source/contributing/documentation.md | 6 +++--- docs/source/upgrade-guide/index.md | 2 +- packages/volto/news/6011.documentation | 1 + requirements-docs.txt | 10 +++++----- 5 files changed, 11 insertions(+), 9 deletions(-) create mode 100644 packages/volto/news/6011.documentation diff --git a/docs/source/conf.py b/docs/source/conf.py index 6360e35dae..0161bc9044 100644 --- 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 index 354f84a18b..e9803214a0 100644 --- 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 color picker widget ``` @@ -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 index 4d6001ebae..3be339ce95 100644 --- 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 new file mode 100644 index 0000000000..b9012da730 --- /dev/null +++ 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 index 315a5acd83..a29144c52a 100644 --- 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