From 35fb31e1ead6936071eb10980d81655870c1662f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 15 May 2024 02:28:24 -0700 Subject: [PATCH 01/34] Add documentation for how to administer Read the Docs for documentation --- Makefile | 4 ++ docs/contributing/documentation/admins.md | 50 ++++++++++++++++++++++- 2 files changed, 53 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index ac8d6062a..f045ce9da 100644 --- a/Makefile +++ b/Makefile @@ -224,6 +224,10 @@ livehtml: deps ## Rebuild Sphinx documentation on changes, with live-reload in --port 8050 \ -b html . "$(BUILDDIR)/html" $(SPHINXOPTS) $(O) +.PHONY: rtd-pr-preview +rtd-pr-preview: bin/python ## Build pull request preview on Read the Docs + cd $(DOCS_DIR) && $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/ + .PHONY: netlify netlify: pip install -r requirements-initial.txt diff --git a/docs/contributing/documentation/admins.md b/docs/contributing/documentation/admins.md index e8d9591a3..36420641d 100644 --- a/docs/contributing/documentation/admins.md +++ b/docs/contributing/documentation/admins.md @@ -4,7 +4,7 @@ myst: "description": "Administrators' guide to writing Plone Documentation. It covers automated deployments, hosting, automated testing, previewing, and importing external package documentation into Plone Documentation." "property=og:description": "Administrators' guide to writing Plone Documentation. It covers automated deployments, hosting, automated testing, previewing, and importing external package documentation into Plone Documentation." "property=og:title": "Administrators Guide" - "keywords": "Plone, Documentation, automated deployments, hosting, automated testing, importing external packages" + "keywords": "Plone, Documentation, automated deployments, hosting, automated testing, importing external packages, preview, build, pull request" --- (administrators-guide-label)= @@ -84,6 +84,54 @@ To make it easier for other contributors to work with your project, update the f Commit and push your changes to a remote, and submit a pull request against [`plone/documentation@6.0`](https://github.com/plone/documentation/compare). +## Add a project to Read the Docs + +To add a new site to Read the Docs to preview documentation or storybooks in pull requests, you need to configure your project's repository and import it into Read the Docs. +You also need an account on Read the Docs and have write access to the repository. + + +### Configuration files + +The following are example files that you can use to configure your project for Read the Docs pull request previews. + +- [Plone Sphinx Theme `Makefile`](https://github.com/plone/plone-sphinx-theme/blob/main/Makefile), specifically the `rtd-pr-preview` section. + This is the command to use to build documentation previews on Read the Docs. +- [Plone Sphinx Theme `requirements-initial.txt`](https://github.com/plone/plone-sphinx-theme/blob/main/requirements-initial.txt) specifies the initial Python packaging tool requirements to set up a virtual environment. +- [Plone Sphinx Theme `requirements-docs.txt`](https://github.com/plone/plone-sphinx-theme/blob/main/requirements-docs.txt) specifies the requirements to use Plone Sphinx Theme and build the docs. +- [Plone Sphinx Theme `.readthedocs.yaml`](https://github.com/plone/plone-sphinx-theme/blob/main/readthedocs.yaml) specifies the configuration and command to build the docs. +- [Plone Sphinx Theme `.github/workflows/rtd-pr-preview.yml`](https://github.com/plone/plone-sphinx-theme/blob/main/.github/workflows/rtd-pr-preview.yml) specifies when to build the docs, specifically only when a pull request is opened against the `main` branch and there are changes to documentation files. + You might need to adjust the branch name, paths, and files to check for changes. + + +### Read the Docs administration + +After logging in to your Read the Docs account, you can import your project. + +1. Click {guilabel}`Add project`. +1. For {guilabel}`Repository name`, enter the GitHub organization, a forward slash, and the repository to import, for example, `plone/volto`. +1. Click {guilabel}`Continue`. +1. In the {guilabel}`Add project` screen, you can configure basic project settings, including its {guilabel}`Name`, {guilabel}`Repository URL`, {guilabel}`Default branch`, and {guilabel}`Language`. + The defaults are usually accurate. +1. Click {guilabel}`Next`. +1. A sample `.readthedocs.yaml` file is suggested, if you have not already added one. +1. Click {guilabel}`Finish`. + Read the Docs will redirect you to the project details, and start building the docs. + +Plone uses an organization on Read the Docs. +The main project is Plone Documentation. +All other Plone projects with documentation should be configured as subprojects. + +```{todo} +Add how to set up a subproject. +``` + +For most Plone projects, you will not want to Read the Docs to publish the `latest` or other specific versions. +Plone projects currently self-host their official documentation. + +1. For the version that you want to deactivate, click its {guilabel}`…` icon, and select {guilabel}`Configure version`. +1. Toggle the {guilabel}`Active` option off, and click {guilabel}`Update version`. + + ## Add a project to Netlify To add a new site to Netlify to preview built documentation or storybooks, you need to add a new site to Netlify. From d69b4935bdff578778d1ea851b539db0d7f98bf6 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 16 May 2024 14:14:43 -0700 Subject: [PATCH 02/34] Remove subprojects mention --- docs/contributing/documentation/admins.md | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/docs/contributing/documentation/admins.md b/docs/contributing/documentation/admins.md index 36420641d..8d2b8c698 100644 --- a/docs/contributing/documentation/admins.md +++ b/docs/contributing/documentation/admins.md @@ -92,7 +92,7 @@ You also need an account on Read the Docs and have write access to the repositor ### Configuration files -The following are example files that you can use to configure your project for Read the Docs pull request previews. +The following are example files that you can use to configure your project for pull request previews on Read the Docs. - [Plone Sphinx Theme `Makefile`](https://github.com/plone/plone-sphinx-theme/blob/main/Makefile), specifically the `rtd-pr-preview` section. This is the command to use to build documentation previews on Read the Docs. @@ -117,14 +117,6 @@ After logging in to your Read the Docs account, you can import your project. 1. Click {guilabel}`Finish`. Read the Docs will redirect you to the project details, and start building the docs. -Plone uses an organization on Read the Docs. -The main project is Plone Documentation. -All other Plone projects with documentation should be configured as subprojects. - -```{todo} -Add how to set up a subproject. -``` - For most Plone projects, you will not want to Read the Docs to publish the `latest` or other specific versions. Plone projects currently self-host their official documentation. From a71e224d874994bfd4512707f12fc471096f12b4 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 16 May 2024 14:16:38 -0700 Subject: [PATCH 03/34] Remove Netlify configuration --- docs/contributing/documentation/admins.md | 48 ----------------------- 1 file changed, 48 deletions(-) diff --git a/docs/contributing/documentation/admins.md b/docs/contributing/documentation/admins.md index 8d2b8c698..462edfaeb 100644 --- a/docs/contributing/documentation/admins.md +++ b/docs/contributing/documentation/admins.md @@ -122,51 +122,3 @@ Plone projects currently self-host their official documentation. 1. For the version that you want to deactivate, click its {guilabel}`…` icon, and select {guilabel}`Configure version`. 1. Toggle the {guilabel}`Active` option off, and click {guilabel}`Update version`. - - -## Add a project to Netlify - -To add a new site to Netlify to preview built documentation or storybooks, you need to add a new site to Netlify. - -1. Visit [Team Overview](https://app.netlify.com/teams/plone/overview). -1. Click {guilabel}`Add a new site` and select {guilabel}`Import an existing project`. -1. Click {guilabel}`Deploy with GitHub`. -1. Select {guilabel}`plone` for the GitHub organization. -1. Click {guilabel}`Configure Netlify on GitHub`. -1. Select the organization to where you want to install Netlify. -1. Click {guilabel}`Select repositories` and select the repository that you want to add. -1. Click {guilabel}`Update access`. -1. Netlify sends an email to members of the email group `admins` at `plone.org`, who need to review and approve the request. - However the email doesn't specify the repository, and admins will not know what to do. - You must send email to that group, including in your request the organization and repository, such as `plone/volto`. -1. The admin must login to GitHub as an organization owner, then navigate to the requested repository's {guilabel}`Settings`. [What else Admin person?] -1. The admin replies to the requestor, letting them know the request was approved. - -From here you need to update your repository to work with Netlify. -For an example, see the following files. - -- [Volto `Makefile`](https://github.com/plone/volto/blob/main/Makefile), specifically the `netlify` section. - This will become the command used to build docs on Netlify. -- [Volto `requirements-docs.txt`](https://github.com/plone/volto/blob/main/requirements-docs.txt) specifies the requirements to build the docs. -- [Volto `netlify.toml`](https://github.com/plone/volto/blob/main/netlify.toml) specifies when to build the docs, specifically only when there are changes to documentation files. - -Finally you need to configure your site in Netlify. -You may have done some of these steps earlier, but you might need to refine them. -The critical pieces are the following. - -1. From the dashboard, select the site to edit it. -1. Click {guilabel}`Site configuration`. -1. One time only, under {guilabel}`General > Site details` click {guilabel}`Change site name`. - A modal dialog appears. - Enter the site name using the pattern `ORGANIZATION_NAME-REPOSITORY_NAME`. - For example, `plone-components`. - Click {guilabel}`Save`. -1. Under {guilabel}`Build & deploy > Continuous deployment`, scroll to {guilabel}`Build settings`, and click {guilabel}`Configure`, then enter the following values. - - {guilabel}`Base directory`: `/` - - {guilabel}`Package directory`: `/` - - {guilabel}`Build command`: `make netlify`. - This is the command you would define in your `Makefile`. - - {guilabel}`Publish directory`: `_build/html`. - This is where the `make` command will output files. - - Finally click {guilabel}`Save`. -1. Under {guilabel}`Build & deploy > Continuous deployment`, scroll to {guilabel}`Branches and deploy contexts`, and click {guilabel}`Configure`, then enter appropriate values. From 03335af1dc22413e345d843d63b765554234ea6d Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 16 May 2024 14:22:46 -0700 Subject: [PATCH 04/34] Update requirements files --- requirements-initial.txt | 7 ++++--- requirements.txt | 13 ++----------- 2 files changed, 6 insertions(+), 14 deletions(-) diff --git a/requirements-initial.txt b/requirements-initial.txt index eb8815a12..fda12989b 100644 --- a/requirements-initial.txt +++ b/requirements-initial.txt @@ -1,4 +1,5 @@ +# requirements-initial.txt # From https://dist.plone.org/release/6-latest/constraints.txt -pip==23.2 -setuptools==68.0.0 -wheel==0.40.0 +pip==24.0 +setuptools==69.5.1 +wheel==0.43.0 diff --git a/requirements.txt b/requirements.txt index a6c516054..1c23eefe7 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,26 +1,17 @@ -docutils<0.17,>=0.15 # sphinx-book-theme 0.2.0 has requirement docutils<0.17,>=0.15 -Sphinx<5,>=3 # sphinx-book-theme 0.3.3 has requirement sphinx<5,>=3 +# requirements.txt graphviz -lesscpy linkify-it-py myst-parser -pydata-sphinx-theme<=0.8.99 # Build fails in 0.9.0. See https://github.com/plone/documentation/issues/1297 +plone-sphinx-theme sphinx-autobuild -sphinx-book-theme==0.3.3 # Temporary pin until we can sort out HTML refactoring. sphinx-copybutton sphinx-design # Documentation only sphinx-examples sphinx-notfound-page # Documentation only sphinx-reredirects sphinx-sitemap -sphinx-togglebutton sphinxcontrib.httpdomain # plone.restapi sphinxcontrib.httpexample # plone.restapi -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 From 25a9e7678ac32e63bdb8c76f6fdba5ca74315657 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 16 May 2024 14:24:20 -0700 Subject: [PATCH 05/34] Remove netlify.toml --- netlify.toml | 6 ------ 1 file changed, 6 deletions(-) delete mode 100644 netlify.toml diff --git a/netlify.toml b/netlify.toml deleted file mode 100644 index 324168726..000000000 --- a/netlify.toml +++ /dev/null @@ -1,6 +0,0 @@ -[build.environment] - PYTHON_VERSION = "3.8" -[[headers]] - for = "/*" - [headers.values] - X-Robots-Tag = "none" From 79e77bec8c7207819c055c3739de97b35c7249bf Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 16 May 2024 14:25:57 -0700 Subject: [PATCH 06/34] Add RTD configuration --- .readthedocs.yaml | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 .readthedocs.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 000000000..6a1a8b771 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,24 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the OS, Python version and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.12" +# nodejs: "19" + commands: + - make rtd-pr-preview + +# Build documentation in the "docs/" directory with Sphinx +#sphinx: +# configuration: docs/conf.py + +# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html +#python: +# install: +# - requirements: docs/requirements.txt From cb5eb31b353cc2cd2d76d2d9a6ed9f95e0402ad9 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 16 May 2024 16:03:40 -0700 Subject: [PATCH 07/34] Update conf.py for new theme --- docs/conf.py | 174 +++++++++++++--------- docs/contributing/documentation/admins.md | 1 + 2 files changed, 104 insertions(+), 71 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 17cfc6bf0..2044e5ca6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -19,7 +19,7 @@ project = "Plone Documentation" copyright = "Plone Foundation" -author = "the Plone community" +author = "Plone Community" trademark_name = "Plone" now = datetime.now() year = str(now.year) @@ -43,10 +43,14 @@ # or your custom ones. extensions = [ "myst_parser", + "notfound.extension", "sphinx.ext.autodoc", + "sphinx.ext.autosummary", # plone.api + "sphinx.ext.graphviz", "sphinx.ext.ifconfig", "sphinx.ext.intersphinx", "sphinx.ext.todo", + "sphinx.ext.viewcode", # plone.api "sphinx_copybutton", "sphinx_design", "sphinx_examples", @@ -56,10 +60,6 @@ "sphinxcontrib.httpexample", # plone.restapi "sphinxcontrib.video", "sphinxext.opengraph", - "sphinx.ext.viewcode", # plone.api - "sphinx.ext.autosummary", # plone.api - "sphinx.ext.graphviz", - "notfound.extension", ] # If true, the Docutils Smart Quotes transform, originally based on SmartyPants @@ -101,7 +101,7 @@ r"https://www.youtube.com/playlist", # volto, TODO remove after installing sphinxcontrib.youtube ] linkcheck_anchors = True -linkcheck_timeout = 10 +linkcheck_timeout = 5 linkcheck_retries = 1 # The suffix of source filenames. @@ -144,18 +144,106 @@ "toc.not_readable", # Suppress `WARNING: toctree contains reference to nonexisting document 'news*'` ] -html_js_files = ["patch_scrollToActive.js", "search_shortcut.js"] +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = "plone_sphinx_theme" +html_logo = "_static/logo.svg" +html_favicon = "_static/favicon.ico" +html_theme_options = { + "article_header_start": ["toggle-primary-sidebar"], + "extra_footer": """

The text and illustrations in this website are licensed by the Plone Foundation under a Creative Commons Attribution 4.0 International license. Plone and the Plone® logo are registered trademarks of the Plone Foundation, registered in the United States and other countries. For guidelines on the permitted uses of the Plone trademarks, see https://plone.org/foundation/logo. All other trademarks are owned by their respective owners.

+

Pull request previews by Read the Docs

""", + "footer_end": ["version.html"], + "icon_links": [ + { + "name": "GitHub", + "url": "https://github.com/plone/documentation", + "icon": "fa-brands fa-square-github", + "type": "fontawesome", + "attributes": { + "target": "_blank", + "rel": "noopener me", + "class": "nav-link custom-fancy-css" + } + }, + { + "name": "Twitter", + "url": "https://twitter.com/plone", + "icon": "fa-brands fa-square-twitter", + "type": "fontawesome", + "attributes": { + "target": "_blank", + "rel": "noopener me", + "class": "nav-link custom-fancy-css" + } + }, + { + "name": "Mastodon", + "url": "https://plone.social/@plone", + "icon": "fa-brands fa-mastodon", + "type": "fontawesome", + "attributes": { + "target": "_blank", + "rel": "noopener me", + "class": "nav-link custom-fancy-css" + } + }, + ], + "logo": { + "text": "Plone Sphinx Theme", + }, + "navigation_with_keys": True, + "path_to_docs": "docs", + "repository_branch": "6.0", + "repository_url": "https://github.com/plone/documentation", + "search_bar_text": "Search", # TODO: Confirm usage of search_bar_text in plone-sphinx-theme + "switcher": { + "json_url": "/_static/switcher.json", + "version_match": version, + }, + "use_edit_page_button": True, + "use_issues_button": True, + "use_repository_button": True, +} + +html_context = { # TODO: verify html_context usage in plone-sphinx-theme + "edit_page_url_template": "https://6.docs.plone.org/contributing/index.html?{{ file_name }}#making-contributions-on-github", +} + +# Announce that we have an opensearch plugin +# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_use_opensearch +html_use_opensearch = "https://6.docs.plone.org" # TODO: Confirm usage of opensearch in theme + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +html_title = "%(project)s v%(release)s" % {"project": project, "release": release} + +# If false, no index is generated. +html_use_index = True + +html_css_files = ["custom.css", ("print.css", {"media": "print"})] +# html_js_files = ["patch_scrollToActive.js", "search_shortcut.js"] ## TODO: Remove patches html_extra_path = [ "robots.txt", ] - html_static_path = [ "volto/_static", "_static", # Last path wins. See https://github.com/plone/documentation/pull/1442 ] -# -- Options for myST markdown conversion to html ----------------------------- + +# -- Options for sphinx_sitemap to html ----------------------------- + +# Used by sphinx_sitemap to generate a sitemap +html_baseurl = "https://6.docs.plone.org/" +# https://sphinx-sitemap.readthedocs.io/en/latest/advanced-configuration.html#customizing-the-url-scheme +sitemap_url_scheme = "{link}" + + +# -- Options for MyST markdown conversion to HTML ----------------------------- # For more information see: # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html @@ -179,6 +267,7 @@ "fawrench": '', } + # -- Intersphinx configuration ---------------------------------- # This extension can generate automatic links to the documentation of objects @@ -220,6 +309,11 @@ ] +# -- sphinx.ext.todo ----------------------- +# See http://sphinx-doc.org/ext/todo.html#confval-todo_include_todos +todo_include_todos = True + + # -- sphinx-notfound-page configuration ---------------------------------- notfound_urls_prefix = "" @@ -236,68 +330,6 @@ } -# -- Options for HTML output ------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = "sphinx_book_theme" - -html_logo = "_static/logo.svg" -html_favicon = "_static/favicon.ico" - -html_css_files = ["custom.css", ("print.css", {"media": "print"})] - -# See http://sphinx-doc.org/ext/todo.html#confval-todo_include_todos -todo_include_todos = True - -# Announce that we have an opensearch plugin -# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_use_opensearch -html_use_opensearch = "https://6.docs.plone.org" - -html_sidebars = { - "**": [ - "sidebar-logo.html", - "search-field.html", - "sbt-sidebar-nav.html", - ] -} - -html_theme_options = { - "path_to_docs": "docs", - "repository_url": "https://github.com/plone/documentation", - "repository_branch": "main", - "use_repository_button": True, - "use_issues_button": True, - "use_edit_page_button": True, - "search_bar_text": "Search", - "switcher": { - "json_url": "/_static/switcher.json", - "version_match": version, - }, - "extra_navbar": """ -

- - plone.org plone.org -

""", - "extra_footer": """

The text and illustrations in this website are licensed by the Plone Foundation under a Creative Commons Attribution 4.0 International license. Plone and the Plone® logo are registered trademarks of the Plone Foundation, registered in the United States and other countries. For guidelines on the permitted uses of the Plone trademarks, see https://plone.org/foundation/logo. All other trademarks are owned by their respective owners.

-

- Deploys by Netlify -

""", -} - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -html_title = "%(project)s v%(release)s" % {"project": project, "release": release} - -# If false, no index is generated. -html_use_index = True - -# Used by sphinx_sitemap to generate a sitemap -html_baseurl = "https://6.docs.plone.org/" -# https://sphinx-sitemap.readthedocs.io/en/latest/advanced-configuration.html#customizing-the-url-scheme -sitemap_url_scheme = "{link}" - # -- Options for HTML help output ------------------------------------------------- # Output file base name for HTML help builder. diff --git a/docs/contributing/documentation/admins.md b/docs/contributing/documentation/admins.md index 462edfaeb..577d973f8 100644 --- a/docs/contributing/documentation/admins.md +++ b/docs/contributing/documentation/admins.md @@ -98,6 +98,7 @@ The following are example files that you can use to configure your project for p This is the command to use to build documentation previews on Read the Docs. - [Plone Sphinx Theme `requirements-initial.txt`](https://github.com/plone/plone-sphinx-theme/blob/main/requirements-initial.txt) specifies the initial Python packaging tool requirements to set up a virtual environment. - [Plone Sphinx Theme `requirements-docs.txt`](https://github.com/plone/plone-sphinx-theme/blob/main/requirements-docs.txt) specifies the requirements to use Plone Sphinx Theme and build the docs. +- [Plone Sphinx Theme `conf.py`](https://github.com/plone/plone-sphinx-theme/blob/main/docs/conf.py) the Sphinx configuration file to build the docs. - [Plone Sphinx Theme `.readthedocs.yaml`](https://github.com/plone/plone-sphinx-theme/blob/main/readthedocs.yaml) specifies the configuration and command to build the docs. - [Plone Sphinx Theme `.github/workflows/rtd-pr-preview.yml`](https://github.com/plone/plone-sphinx-theme/blob/main/.github/workflows/rtd-pr-preview.yml) specifies when to build the docs, specifically only when a pull request is opened against the `main` branch and there are changes to documentation files. You might need to adjust the branch name, paths, and files to check for changes. From 96070189fdd7fc2f4cd86c74ceba270ceff8999f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 16 May 2024 16:04:09 -0700 Subject: [PATCH 08/34] Add configuration for pull request previews on RTD --- .github/workflows/rtd-pr-preview.yml | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 .github/workflows/rtd-pr-preview.yml diff --git a/.github/workflows/rtd-pr-preview.yml b/.github/workflows/rtd-pr-preview.yml new file mode 100644 index 000000000..bf7bd5aef --- /dev/null +++ b/.github/workflows/rtd-pr-preview.yml @@ -0,0 +1,22 @@ +# .github/workflows/rtd-pr-preview.yml +name: readthedocs/actions +on: + pull_request_target: + types: + - opened + # Execute this action only on PRs that touch + # documentation files. + # paths: + # - "docs/**" + +permissions: + pull-requests: write + +jobs: + documentation-links: + runs-on: ubuntu-latest + steps: + - uses: readthedocs/actions/preview@v1 + with: + project-slug: "plone6" + single-version: "true" From c23aa55618600d9e144ca6f1e1ca8a8ce56c892d Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 16 May 2024 16:09:41 -0700 Subject: [PATCH 09/34] Try using deps to pull in submodules and create symlinks --- submodules/volto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/submodules/volto b/submodules/volto index 96eb4fa4c..db23888c2 160000 --- a/submodules/volto +++ b/submodules/volto @@ -1 +1 @@ -Subproject commit 96eb4fa4c0a1cb28e89f8f6e457978f748cc5112 +Subproject commit db23888c25377bc42973900ea9bac3d6c0373563 From 6e48d39166db16a2d53d7a1834bf0945d73b84e3 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 16 May 2024 16:15:27 -0700 Subject: [PATCH 10/34] RTD cannot run multiple make targets --- Makefile | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Makefile b/Makefile index f045ce9da..d267c1edd 100644 --- a/Makefile +++ b/Makefile @@ -226,6 +226,12 @@ livehtml: deps ## Rebuild Sphinx documentation on changes, with live-reload in .PHONY: rtd-pr-preview rtd-pr-preview: bin/python ## Build pull request preview on Read the Docs + git submodule init; \ + git submodule update; \ + pip install -e submodules/plone.api[test]; \ + ln -s ../submodules/volto/docs/source ./docs/volto + ln -s ../submodules/plone.restapi ./docs/plone.restapi + ln -s ../submodules/plone.api/docs ./docs/plone.api cd $(DOCS_DIR) && $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/ .PHONY: netlify From f4d00765a12a1ee80f924c08aee3cf01babd559d Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 16 May 2024 16:30:29 -0700 Subject: [PATCH 11/34] Remove obsolete Sphinx template `_templates/sections/header-article.html` --- docs/_templates/sections/header-article.html | 35 -------------------- 1 file changed, 35 deletions(-) delete mode 100644 docs/_templates/sections/header-article.html diff --git a/docs/_templates/sections/header-article.html b/docs/_templates/sections/header-article.html deleted file mode 100644 index 136ce58e5..000000000 --- a/docs/_templates/sections/header-article.html +++ /dev/null @@ -1,35 +0,0 @@ -{# To trigger whether the TOC and its button show up #} -{% set page_toc = generate_toc_html() %} -{% from "../macros/buttons.html" import render_funcs, render_label_input_button with context %} - -
-
- {% if theme_single_page != True %} - {{ render_label_input_button(for_input="__navigation", tooltip="Toggle navigation", icon="fas fa-bars", tooltip_placement="right") }} - {% endif %} -
-
- {{ title|striptags|e }}{%- for parent in parents[:1] %} – {{ parent.title }}{%- endfor %} -
-
- {%- for button in header_buttons -%} - {{ render_funcs[button.pop("type")](**button) }} - {%- endfor -%} - - {% if page_toc -%} - {{ render_label_input_button("__page-toc", icon="fas fa-list", label="page-toc") }} - {%- endif %} -
-
- - -
- {%- if page_toc | length >= 1 %} -
- {{ translate(theme_toc_title) }} -
- - {%- endif %} -
From 36c78cb028980649a8f572f9b0b811a26393c299 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 16 May 2024 17:47:19 -0700 Subject: [PATCH 12/34] Purge Netlify --- Makefile | 13 ------------- docs/netlify_robots.txt | 3 --- 2 files changed, 16 deletions(-) delete mode 100644 docs/netlify_robots.txt diff --git a/Makefile b/Makefile index d267c1edd..b76a84ff4 100644 --- a/Makefile +++ b/Makefile @@ -234,19 +234,6 @@ rtd-pr-preview: bin/python ## Build pull request preview on Read the Docs ln -s ../submodules/plone.api/docs ./docs/plone.api cd $(DOCS_DIR) && $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/ -.PHONY: netlify -netlify: - pip install -r requirements-initial.txt - pip install -r requirements.txt - pip install -r requirements-netlify.txt - git submodule init; \ - git submodule update; \ - pip install -e submodules/plone.api[test]; \ - ln -s ../submodules/volto/docs/source ./docs/volto - ln -s ../submodules/plone.restapi ./docs/plone.restapi - ln -s ../submodules/plone.api/docs ./docs/plone.api - cd $(DOCS_DIR) && sphinx-build -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html && cp ./netlify_robots.txt $(BUILDDIR)/html/robots.txt - .PHONY: storybook storybook: cd submodules/volto && pnpm i && pnpm build:registry && pnpm --filter @plone/volto build-storybook -o ../../../../_build/html/storybook diff --git a/docs/netlify_robots.txt b/docs/netlify_robots.txt deleted file mode 100644 index 0a875a487..000000000 --- a/docs/netlify_robots.txt +++ /dev/null @@ -1,3 +0,0 @@ -# Disallow all user agents from indexing pages and links in the site on Netlify only. -User-agent: * -Disallow: / From 4344e0e74a779ed412890967855f99a82e763087 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 16 May 2024 18:21:16 -0700 Subject: [PATCH 13/34] Attempt to make plone.api importable to Sphinx --- docs/conf.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 2044e5ca6..f6a5e854a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -10,9 +10,10 @@ # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # -# import os -# import sys -# sys.path.insert(0, os.path.abspath(".")) +import os +import sys +# Attempt to make plone.api importable to Sphinx +sys.path.insert(0, os.path.abspath(os.path.join("..", ".."))) # -- Project information ----------------------------------------------------- From bef89c489b20fe1ff9a4db808bc1e9fd3d7bcbce Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 16 May 2024 20:13:16 -0700 Subject: [PATCH 14/34] Attempt to make plone.api importable to Sphinx --- docs/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index f6a5e854a..d9f8670a2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -13,7 +13,8 @@ import os import sys # Attempt to make plone.api importable to Sphinx -sys.path.insert(0, os.path.abspath(os.path.join("..", ".."))) +sys.path.insert(0, os.path.abspath(".")) +# sys.path.insert(0, os.path.abspath(os.path.join("..", ".."))) # -- Project information ----------------------------------------------------- From dbe975a02a95d564dfceb6167658f75bef59ee53 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 16 May 2024 20:43:10 -0700 Subject: [PATCH 15/34] Attempt to make plone.api importable to Sphinx --- docs/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index d9f8670a2..4c4dec830 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -13,9 +13,9 @@ import os import sys # Attempt to make plone.api importable to Sphinx -sys.path.insert(0, os.path.abspath(".")) +# sys.path.insert(0, os.path.abspath(".")) # sys.path.insert(0, os.path.abspath(os.path.join("..", ".."))) - +sys.path.insert(0, os.path.abspath("../submodules/plone.api/src")) # -- Project information ----------------------------------------------------- From 37a8ed4cb3df280a399e49b11d7a3067d595f16a Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 16 May 2024 20:51:25 -0700 Subject: [PATCH 16/34] Attempt to make plone.api importable to Sphinx --- docs/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 4c4dec830..c2fad13d0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -15,7 +15,8 @@ # Attempt to make plone.api importable to Sphinx # sys.path.insert(0, os.path.abspath(".")) # sys.path.insert(0, os.path.abspath(os.path.join("..", ".."))) -sys.path.insert(0, os.path.abspath("../submodules/plone.api/src")) +# sys.path.insert(0, os.path.abspath("../submodules/plone.api/src")) +sys.path.insert(0, os.path.abspath("../submodules/plone.api/src/plone")) # -- Project information ----------------------------------------------------- From 14bb19e2716453bc1a374cfb67883b135f5dc203 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 16 May 2024 20:56:20 -0700 Subject: [PATCH 17/34] Attempt to make plone.api importable to Sphinx --- docs/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/conf.py b/docs/conf.py index c2fad13d0..48fbda7bf 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -17,6 +17,7 @@ # sys.path.insert(0, os.path.abspath(os.path.join("..", ".."))) # sys.path.insert(0, os.path.abspath("../submodules/plone.api/src")) sys.path.insert(0, os.path.abspath("../submodules/plone.api/src/plone")) +print("======\n" + sys.path + "\n======\n") # -- Project information ----------------------------------------------------- From 5aceb91d6bd18df750fe40011fc509eac2e002d2 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 16 May 2024 20:59:21 -0700 Subject: [PATCH 18/34] Attempt to make plone.api importable to Sphinx --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 48fbda7bf..0b21fe8c3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -17,7 +17,7 @@ # sys.path.insert(0, os.path.abspath(os.path.join("..", ".."))) # sys.path.insert(0, os.path.abspath("../submodules/plone.api/src")) sys.path.insert(0, os.path.abspath("../submodules/plone.api/src/plone")) -print("======\n" + sys.path + "\n======\n") +print("======\n" + str(sys.path) + "\n======\n") # -- Project information ----------------------------------------------------- From f28a9660800d851e766ff0ef9edf6f400e0b68b4 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 16 May 2024 22:34:40 -0700 Subject: [PATCH 19/34] Attempt to make plone.api importable to Sphinx --- docs/conf.py | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 0b21fe8c3..98ac47054 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -15,9 +15,11 @@ # Attempt to make plone.api importable to Sphinx # sys.path.insert(0, os.path.abspath(".")) # sys.path.insert(0, os.path.abspath(os.path.join("..", ".."))) -# sys.path.insert(0, os.path.abspath("../submodules/plone.api/src")) -sys.path.insert(0, os.path.abspath("../submodules/plone.api/src/plone")) -print("======\n" + str(sys.path) + "\n======\n") +sys.path.insert(0, os.path.abspath("../submodules/plone.api/src")) +# sys.path.insert(0, os.path.abspath("../submodules/plone.api/src/plone")) +print("====== sys.path ======\n" + str(sys.path) + "\n======\n") +print("====== os.listdir() ======\n" + str(os.listdir()) + "\n======\n") +print("====== os.listdir(sys.path[0]) ======\n" + str(os.listdir(sys.path[0])) + "\n======\n") # -- Project information ----------------------------------------------------- From 77a429906f8303a90c8e43a7e16124e9c0345cbe Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 16 May 2024 23:02:34 -0700 Subject: [PATCH 20/34] Attempt to make plone.api importable to Sphinx --- Makefile | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Makefile b/Makefile index b76a84ff4..b52f75a86 100644 --- a/Makefile +++ b/Makefile @@ -226,9 +226,9 @@ livehtml: deps ## Rebuild Sphinx documentation on changes, with live-reload in .PHONY: rtd-pr-preview rtd-pr-preview: bin/python ## Build pull request preview on Read the Docs - git submodule init; \ - git submodule update; \ - pip install -e submodules/plone.api[test]; \ + git submodule init + git submodule update + pip install -e submodules/plone.api[test] ln -s ../submodules/volto/docs/source ./docs/volto ln -s ../submodules/plone.restapi ./docs/plone.restapi ln -s ../submodules/plone.api/docs ./docs/plone.api From 103ab2ef2066d1bc0d589127af9b90d19e4f3def Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 16 May 2024 23:08:43 -0700 Subject: [PATCH 21/34] Attempt to make plone.api importable to Sphinx by bypassing Makefile --- .readthedocs.yaml | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 6a1a8b771..d083f3b20 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -12,7 +12,17 @@ build: python: "3.12" # nodejs: "19" commands: - - make rtd-pr-preview +# - make rtd-pr-preview + - pip install -r requirements-initial.txt + - pip install -r requirements.txt + - git submodule init + - git submodule update + - pip install -e submodules/plone.api[test] + - ln -s ../submodules/volto/docs/source ./docs/volto + - ln -s ../submodules/plone.restapi ./docs/plone.restapi + - ln -s ../submodules/plone.api/docs ./docs/plone.api + - cd $(DOCS_DIR) && $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/ + # Build documentation in the "docs/" directory with Sphinx #sphinx: From be920d4e141060dbc48d17f66618c12fafd1153b Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 16 May 2024 23:14:55 -0700 Subject: [PATCH 22/34] Attempt to make plone.api importable to Sphinx by bypassing Makefile --- .readthedocs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index d083f3b20..81f2a399e 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -21,7 +21,7 @@ build: - ln -s ../submodules/volto/docs/source ./docs/volto - ln -s ../submodules/plone.restapi ./docs/plone.restapi - ln -s ../submodules/plone.api/docs ./docs/plone.api - - cd $(DOCS_DIR) && $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/ + - cd ./docs/ && "$(realpath bin/sphinx-build)" -b html -d $(BUILDDIR)/doctrees . ${READTHEDOCS_OUTPUT}/html/ # Build documentation in the "docs/" directory with Sphinx From bd5c377eec9fcf68ef04cde57330e568eae6481a Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 16 May 2024 23:19:53 -0700 Subject: [PATCH 23/34] Attempt to make plone.api importable to Sphinx by using its system Python instead of the Python in the Makefile --- .readthedocs.yaml | 12 +----------- Makefile | 4 +++- 2 files changed, 4 insertions(+), 12 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 81f2a399e..6a1a8b771 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -12,17 +12,7 @@ build: python: "3.12" # nodejs: "19" commands: -# - make rtd-pr-preview - - pip install -r requirements-initial.txt - - pip install -r requirements.txt - - git submodule init - - git submodule update - - pip install -e submodules/plone.api[test] - - ln -s ../submodules/volto/docs/source ./docs/volto - - ln -s ../submodules/plone.restapi ./docs/plone.restapi - - ln -s ../submodules/plone.api/docs ./docs/plone.api - - cd ./docs/ && "$(realpath bin/sphinx-build)" -b html -d $(BUILDDIR)/doctrees . ${READTHEDOCS_OUTPUT}/html/ - + - make rtd-pr-preview # Build documentation in the "docs/" directory with Sphinx #sphinx: diff --git a/Makefile b/Makefile index b52f75a86..154c9fa0c 100644 --- a/Makefile +++ b/Makefile @@ -225,7 +225,9 @@ livehtml: deps ## Rebuild Sphinx documentation on changes, with live-reload in -b html . "$(BUILDDIR)/html" $(SPHINXOPTS) $(O) .PHONY: rtd-pr-preview -rtd-pr-preview: bin/python ## Build pull request preview on Read the Docs +rtd-pr-preview: ## Build pull request preview on Read the Docs + pip install -r requirements-initial.txt + pip install -r requirements.txt git submodule init git submodule update pip install -e submodules/plone.api[test] From 0c67dd271ee607891412b6a13cc58b2628660c62 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 16 May 2024 23:28:05 -0700 Subject: [PATCH 24/34] Attempt to make plone.api importable to Sphinx by using its system Python instead of the Python in the Makefile --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 154c9fa0c..98e33474b 100644 --- a/Makefile +++ b/Makefile @@ -234,7 +234,7 @@ rtd-pr-preview: ## Build pull request preview on Read the Docs ln -s ../submodules/volto/docs/source ./docs/volto ln -s ../submodules/plone.restapi ./docs/plone.restapi ln -s ../submodules/plone.api/docs ./docs/plone.api - cd $(DOCS_DIR) && $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/ + cd $(DOCS_DIR) && sphinx-build -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/ .PHONY: storybook storybook: From 0a4968ce037340e891845f4038f941a03bd5f456 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 17 May 2024 01:06:00 -0700 Subject: [PATCH 25/34] Fix link references --- .../upgrading/version-specific-migration/upgrade-to-60.md | 2 +- docs/contributing/documentation/themes-and-extensions.md | 4 ++-- docs/contributing/index.md | 2 +- docs/install/manage-add-ons-packages.md | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/backend/upgrading/version-specific-migration/upgrade-to-60.md b/docs/backend/upgrading/version-specific-migration/upgrade-to-60.md index 34ce02e2a..76b1378d5 100644 --- a/docs/backend/upgrading/version-specific-migration/upgrade-to-60.md +++ b/docs/backend/upgrading/version-specific-migration/upgrade-to-60.md @@ -168,7 +168,7 @@ The standard theme in Classic UI was updated to Bootstrap 5, CSS variables, and If you have a theme that builds on Barceloneta, you most likely need various changes. It may be best to start with a fresh theme, and try to keep the changes minimal. -The training documentation lists {doc}`three possible theming strategies `: +The training documentation lists {doc}`three possible theming strategies `: - Create a theme based on Barceloneta. - Create a theme from scratch. diff --git a/docs/contributing/documentation/themes-and-extensions.md b/docs/contributing/documentation/themes-and-extensions.md index 1e3d80c9d..38642ad33 100644 --- a/docs/contributing/documentation/themes-and-extensions.md +++ b/docs/contributing/documentation/themes-and-extensions.md @@ -58,9 +58,9 @@ We use several MyST and Sphinx extensions to enhance the presentation of Plone d - [`sphinx_reredirects`](https://documatt.com/sphinx-reredirects/) handles redirects for moved pages. - [`sphinx_sitemap`](https://pypi.org/project/sphinx-sitemap/) generates multiversion and multilanguage [sitemaps.org](https://www.sitemaps.org/protocol.html) compliant sitemaps. - [`sphinxcontrib.httpdomain`](https://sphinxcontrib-httpdomain.readthedocs.io/en/stable/) provides a Sphinx domain for describing HTTP APIs. - It is used by Plone's {doc}`plone.restapi/docs/source/index`. + It is used by Plone's {doc}`/plone.restapi/docs/source/index`. - [`sphinxcontrib.httpexample`](https://sphinxcontrib-httpexample.readthedocs.io/en/latest/) enhances `sphinxcontrib-httpdomain` by generating RESTful HTTP API call examples for different tools from a single HTTP request example. Supported tools include [curl](https://curl.se/), [wget](https://www.gnu.org/software/wget/), [httpie](https://httpie.io/), and [python-requests](https://requests.readthedocs.io/en/latest/). - It is used by Plone's {doc}`plone.restapi/docs/source/index`. + It is used by Plone's {doc}`/plone.restapi/docs/source/index`. - [`sphinxcontrib.video`](https://pypi.org/project/sphinxcontrib-video/) allows you to embed local videos as defined by the HTML5 standard. - [`sphinxext.opengraph`](https://pypi.org/project/sphinxext-opengraph/) generates [OpenGraph metadata](https://ogp.me/). diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 24be3d4ff..51d2a14f2 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -165,7 +165,7 @@ Plone API Plone REST API : A RESTful API for Plone. - See {doc}`plone.restapi/docs/source/contributing/index`. + See {doc}`/plone.restapi/docs/source/contributing/index`. Volto : Plone 6 default frontend. diff --git a/docs/install/manage-add-ons-packages.md b/docs/install/manage-add-ons-packages.md index e1b432dfe..1f328db5f 100644 --- a/docs/install/manage-add-ons-packages.md +++ b/docs/install/manage-add-ons-packages.md @@ -50,7 +50,7 @@ For a complete list of features, usage, and options, read [`cookiecutter-zope-in This section describes how to manage packages for the Plone backend with `mxdev`. -For developing add-ons for the Plone frontend, Volto, see {doc}`volto/addons/index`. +For developing add-ons for the Plone frontend, Volto, see {doc}`/volto/addons/index`. (manage-the-problem-with-pip-label)= From d5d6974ab306e7c6414bd1a2a3decfa380e655bd Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 18 May 2024 04:27:45 -0700 Subject: [PATCH 26/34] Relocate static files --- {docs => _docs}/_static/custom.css | 0 docs/_static/documentation-custom.css | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename {docs => _docs}/_static/custom.css (100%) create mode 100644 docs/_static/documentation-custom.css diff --git a/docs/_static/custom.css b/_docs/_static/custom.css similarity index 100% rename from docs/_static/custom.css rename to _docs/_static/custom.css diff --git a/docs/_static/documentation-custom.css b/docs/_static/documentation-custom.css new file mode 100644 index 000000000..e69de29bb From 35ab6fbf6a605ef580e87f24be60b9e9103976ba Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 18 May 2024 04:28:02 -0700 Subject: [PATCH 27/34] Purge Netlify --- requirements-netlify.txt | 1 - 1 file changed, 1 deletion(-) delete mode 100644 requirements-netlify.txt diff --git a/requirements-netlify.txt b/requirements-netlify.txt deleted file mode 100644 index 4b7c5cccc..000000000 --- a/requirements-netlify.txt +++ /dev/null @@ -1 +0,0 @@ -plone-autoform<=1.99 \ No newline at end of file From d99838ec8650ae4269c5f85598a911055c5e8451 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 18 May 2024 04:28:37 -0700 Subject: [PATCH 28/34] Clean up `conf.py` --- docs/conf.py | 29 ++++++++++------------------- 1 file changed, 10 insertions(+), 19 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 98ac47054..31d297cfa 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -12,14 +12,8 @@ # import os import sys -# Attempt to make plone.api importable to Sphinx -# sys.path.insert(0, os.path.abspath(".")) -# sys.path.insert(0, os.path.abspath(os.path.join("..", ".."))) sys.path.insert(0, os.path.abspath("../submodules/plone.api/src")) -# sys.path.insert(0, os.path.abspath("../submodules/plone.api/src/plone")) -print("====== sys.path ======\n" + str(sys.path) + "\n======\n") -print("====== os.listdir() ======\n" + str(os.listdir()) + "\n======\n") -print("====== os.listdir(sys.path[0]) ======\n" + str(os.listdir(sys.path[0])) + "\n======\n") + # -- Project information ----------------------------------------------------- @@ -39,6 +33,7 @@ # The full version, including alpha/beta/rc tags. release = "6.0" + # -- General configuration ---------------------------------------------------- # Add any paths that contain templates here, relative to this directory. @@ -161,7 +156,7 @@ html_theme_options = { "article_header_start": ["toggle-primary-sidebar"], "extra_footer": """

The text and illustrations in this website are licensed by the Plone Foundation under a Creative Commons Attribution 4.0 International license. Plone and the Plone® logo are registered trademarks of the Plone Foundation, registered in the United States and other countries. For guidelines on the permitted uses of the Plone trademarks, see https://plone.org/foundation/logo. All other trademarks are owned by their respective owners.

-

Pull request previews by Read the Docs

""", +

Pull request previews by Read the Docs.

""", "footer_end": ["version.html"], "icon_links": [ { @@ -199,7 +194,7 @@ }, ], "logo": { - "text": "Plone Sphinx Theme", + "text": "Plone Documentation", }, "navigation_with_keys": True, "path_to_docs": "docs", @@ -215,6 +210,8 @@ "use_repository_button": True, } +# suggest edit link +# remark: {{ file_name }} is mandatory in "edit_page_url_template" html_context = { # TODO: verify html_context usage in plone-sphinx-theme "edit_page_url_template": "https://6.docs.plone.org/contributing/index.html?{{ file_name }}#making-contributions-on-github", } @@ -241,7 +238,7 @@ ] -# -- Options for sphinx_sitemap to html ----------------------------- +# -- Options for sphinx_sitemap to HTML ----------------------------- # Used by sphinx_sitemap to generate a sitemap html_baseurl = "https://6.docs.plone.org/" @@ -315,12 +312,12 @@ ] -# -- sphinx.ext.todo ----------------------- +# -- Options for sphinx.ext.todo ----------------------- # See http://sphinx-doc.org/ext/todo.html#confval-todo_include_todos todo_include_todos = True -# -- sphinx-notfound-page configuration ---------------------------------- +# -- Options for sphinx-notfound-page ---------------------------------- notfound_urls_prefix = "" notfound_template = "404.html" @@ -351,7 +348,7 @@ "index", "PloneDocumentation.tex", "Plone Documentation", - "The Plone community", + "Plone Community", "manual", ), ] @@ -361,12 +358,6 @@ latex_logo = "_static/logo_2x.png" -# suggest edit link -# remark: {{ file_name }} is mandatory in "edit_page_url_template" -html_context = { - "edit_page_url_template": "https://6.docs.plone.org/contributing/index.html?{{ file_name }}#making-contributions-on-github", -} - # An extension that allows replacements for code blocks that # are not supported in `rst_epilog` or other substitutions. # https://stackoverflow.com/a/56328457/2214933 From ada6b810e748b75dbfae6891602270685ed06ca1 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 19 May 2024 03:54:10 -0700 Subject: [PATCH 29/34] Fix link --- docs/contributing/documentation/admins.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/documentation/admins.md b/docs/contributing/documentation/admins.md index 577d973f8..1cfa876f3 100644 --- a/docs/contributing/documentation/admins.md +++ b/docs/contributing/documentation/admins.md @@ -99,7 +99,7 @@ The following are example files that you can use to configure your project for p - [Plone Sphinx Theme `requirements-initial.txt`](https://github.com/plone/plone-sphinx-theme/blob/main/requirements-initial.txt) specifies the initial Python packaging tool requirements to set up a virtual environment. - [Plone Sphinx Theme `requirements-docs.txt`](https://github.com/plone/plone-sphinx-theme/blob/main/requirements-docs.txt) specifies the requirements to use Plone Sphinx Theme and build the docs. - [Plone Sphinx Theme `conf.py`](https://github.com/plone/plone-sphinx-theme/blob/main/docs/conf.py) the Sphinx configuration file to build the docs. -- [Plone Sphinx Theme `.readthedocs.yaml`](https://github.com/plone/plone-sphinx-theme/blob/main/readthedocs.yaml) specifies the configuration and command to build the docs. +- [Plone Sphinx Theme `.readthedocs.yaml`](https://github.com/plone/plone-sphinx-theme/blob/main/.readthedocs.yaml) specifies the configuration and command to build the docs. - [Plone Sphinx Theme `.github/workflows/rtd-pr-preview.yml`](https://github.com/plone/plone-sphinx-theme/blob/main/.github/workflows/rtd-pr-preview.yml) specifies when to build the docs, specifically only when a pull request is opened against the `main` branch and there are changes to documentation files. You might need to adjust the branch name, paths, and files to check for changes. From 097546f633d173515317a22a0c9b80e718894ea5 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 20 May 2024 14:55:46 -0700 Subject: [PATCH 30/34] Revert "Try using deps to pull in submodules and create symlinks" This reverts commit c23aa55618600d9e144ca6f1e1ca8a8ce56c892d. --- submodules/volto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/submodules/volto b/submodules/volto index db23888c2..96eb4fa4c 160000 --- a/submodules/volto +++ b/submodules/volto @@ -1 +1 @@ -Subproject commit db23888c25377bc42973900ea9bac3d6c0373563 +Subproject commit 96eb4fa4c0a1cb28e89f8f6e457978f748cc5112 From 35372cfab41d371d81b8b176419e572d45784fff Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 20 May 2024 23:01:20 -0700 Subject: [PATCH 31/34] Rename headings and improve flow --- docs/contributing/documentation/admins.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/contributing/documentation/admins.md b/docs/contributing/documentation/admins.md index 1cfa876f3..d6ad0cee8 100644 --- a/docs/contributing/documentation/admins.md +++ b/docs/contributing/documentation/admins.md @@ -84,9 +84,9 @@ To make it easier for other contributors to work with your project, update the f Commit and push your changes to a remote, and submit a pull request against [`plone/documentation@6.0`](https://github.com/plone/documentation/compare). -## Add a project to Read the Docs +## Pull request preview builds -To add a new site to Read the Docs to preview documentation or storybooks in pull requests, you need to configure your project's repository and import it into Read the Docs. +To preview pull request builds of documentation or Storybooks on Read the Docs, you need to configure your project's repository and import it into Read the Docs. You also need an account on Read the Docs and have write access to the repository. @@ -104,7 +104,7 @@ The following are example files that you can use to configure your project for p You might need to adjust the branch name, paths, and files to check for changes. -### Read the Docs administration +### Import your project After logging in to your Read the Docs account, you can import your project. From df9a0eeb3f09ca70caf4075a8cf753a4fa24f718 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 20 May 2024 23:02:02 -0700 Subject: [PATCH 32/34] Rewrite search engine indexing section Add Cancel builds programmatically section Add Cancel builds on a branch section --- docs/contributing/documentation/admins.md | 55 +++++++++++++++++++++-- 1 file changed, 51 insertions(+), 4 deletions(-) diff --git a/docs/contributing/documentation/admins.md b/docs/contributing/documentation/admins.md index d6ad0cee8..791df1c2f 100644 --- a/docs/contributing/documentation/admins.md +++ b/docs/contributing/documentation/admins.md @@ -118,8 +118,55 @@ After logging in to your Read the Docs account, you can import your project. 1. Click {guilabel}`Finish`. Read the Docs will redirect you to the project details, and start building the docs. -For most Plone projects, you will not want to Read the Docs to publish the `latest` or other specific versions. -Plone projects currently self-host their official documentation. -1. For the version that you want to deactivate, click its {guilabel}`…` icon, and select {guilabel}`Configure version`. -1. Toggle the {guilabel}`Active` option off, and click {guilabel}`Update version`. +### Search engine indexing + +Many Plone projects currently self-host their official documentation at {doc}`/index`. +These projects get indexed by search engines. + +For pull request previews, unsupported branches or versions, or other situations, you most likely do not want search engines to index your documentation. +Your options include the following. + +- Deactivate your build +- Hide your build +- Create a custom {file}`robots.txt` file to discourage, but not absolutely prevent, search engine indexing + +For the last option, you can configure Sphinx to copy the {file}`robots.txt` file. +However, if you want to have two versions of a {file}`robots.txt` file—say one that allows indexing of your official documentation and another that discourages indexing—you can configure your automation to copy it into place with a command such as the following. + +```shell +cp source-path/block-robots.txt docs-root-path/robots.txt +``` + +```{seealso} +- [Automation rules](https://docs.readthedocs.io/en/stable/automation-rules.html) +- [Versions](https://docs.readthedocs.io/en/stable/versions.html) +- [Managing versions automatically](https://docs.readthedocs.io/en/stable/guides/automation-rules.html) +- [`robots.txt` support](https://docs.readthedocs.io/en/stable/reference/robots.html) +``` + + +### Cancel builds programmatically + +You might want to cancel a build programmatically when certain conditions are met. +You can do this through your {file}`.readthedocs.yaml` file. +Read the Docs covers a few scenarios in its documentation, [Cancel build based on a condition](https://docs.readthedocs.io/en/stable/build-customization.html#cancel-build-based-on-a-condition). + + +#### Cancel builds on a branch + +If you have pull request preview builds enabled, any pull request to any branch will trigger a build. +If you do not want to build documentation on a specific branch, you can cancel a build programmatically through your {file}`.readthedocs.yaml` file. + +```yaml +version: 2 +build: + os: "ubuntu-22.04" + tools: + python: "3.12" + jobs: + post_checkout: + # Cancel the Read the Docs build + # https://docs.readthedocs.io/en/stable/build-customization.html#cancel-build-based-on-a-condition + - exit 183; +``` From 84c0ff05398bfe31c9e24a973145d6c1d886dcf1 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 20 May 2024 23:18:12 -0700 Subject: [PATCH 33/34] Update configuration to build only on changes to docs files --- .readthedocs.yaml | 26 ++++++++++---------- docs/contributing/documentation/admins.md | 29 +++++++++++++++++++++++ 2 files changed, 43 insertions(+), 12 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 6a1a8b771..16b5e05eb 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -10,15 +10,17 @@ build: os: ubuntu-22.04 tools: python: "3.12" -# nodejs: "19" - commands: - - make rtd-pr-preview - -# Build documentation in the "docs/" directory with Sphinx -#sphinx: -# configuration: docs/conf.py - -# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html -#python: -# install: -# - requirements: docs/requirements.txt + jobs: + post_checkout: + # Cancel building pull requests when there aren't changes in the docs directory or YAML file. + # You can add any other files or directories that you'd like here as well, + # like your docs requirements file, or other files that will change your docs build. + # + # If there are no changes (git diff exits with 0) we force the command to return with 183. + # This is a special exit code on Read the Docs that will cancel the build immediately. + - | + if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- docs/ .readthedocs.yaml requirements-initial.txt requirements.txt; + then + exit 183; + fi + - make rtd-pr-preview diff --git a/docs/contributing/documentation/admins.md b/docs/contributing/documentation/admins.md index 791df1c2f..fe3c2db89 100644 --- a/docs/contributing/documentation/admins.md +++ b/docs/contributing/documentation/admins.md @@ -153,6 +153,35 @@ You can do this through your {file}`.readthedocs.yaml` file. Read the Docs covers a few scenarios in its documentation, [Cancel build based on a condition](https://docs.readthedocs.io/en/stable/build-customization.html#cancel-build-based-on-a-condition). +#### Build only on changes + +When there are no changes to documentation, it is not necessary to build it. +You can save time and energy by programmatically building documentation only when it changes. + +In your {file}`.readthedocs.yaml` file, you could use the following example. + +```yaml +version: 2 +build: + os: "ubuntu-22.04" + tools: + python: "3.12" + jobs: + post_checkout: + # Cancel building pull requests when there aren't changes in the docs directory or YAML file. + # You can add any other files or directories that you'd like here as well, + # like your docs requirements file, or other files that will change your docs build. + # + # If there are no changes (git diff exits with 0) we force the command to return with 183. + # This is a special exit code on Read the Docs that will cancel the build immediately. + - | + if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- docs/ .readthedocs.yaml requirements-initial.txt requirements.txt; + then + exit 183; + fi +``` + + #### Cancel builds on a branch If you have pull request preview builds enabled, any pull request to any branch will trigger a build. From ca19f1ce9a847797f13774f55fb06754907aec7e Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 20 May 2024 23:21:10 -0700 Subject: [PATCH 34/34] Use commands instead --- .readthedocs.yaml | 27 +++++++++++++-------------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 16b5e05eb..8beeb58c4 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -10,17 +10,16 @@ build: os: ubuntu-22.04 tools: python: "3.12" - jobs: - post_checkout: - # Cancel building pull requests when there aren't changes in the docs directory or YAML file. - # You can add any other files or directories that you'd like here as well, - # like your docs requirements file, or other files that will change your docs build. - # - # If there are no changes (git diff exits with 0) we force the command to return with 183. - # This is a special exit code on Read the Docs that will cancel the build immediately. - - | - if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- docs/ .readthedocs.yaml requirements-initial.txt requirements.txt; - then - exit 183; - fi - - make rtd-pr-preview + commands: + # Cancel building pull requests when there aren't changes in the docs directory or YAML file. + # You can add any other files or directories that you'd like here as well, + # like your docs requirements file, or other files that will change your docs build. + # + # If there are no changes (git diff exits with 0) we force the command to return with 183. + # This is a special exit code on Read the Docs that will cancel the build immediately. + - | + if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- docs/ .readthedocs.yaml requirements-initial.txt requirements.txt; + then + exit 183; + fi + - make rtd-pr-preview