From 35fb31e1ead6936071eb10980d81655870c1662f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 15 May 2024 02:28:24 -0700 Subject: [PATCH 01/42] 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 ac8d6062a1..f045ce9dab 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 e8d9591a3c..36420641dc 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/42] 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 36420641dc..8d2b8c6986 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/42] 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 8d2b8c6986..462edfaeb6 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/42] 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 eb8815a127..fda12989bc 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 a6c516054c..1c23eefe75 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/42] 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 3241687267..0000000000 --- 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/42] 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 0000000000..6a1a8b7718 --- /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/42] 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 17cfc6bf0f..2044e5ca61 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 462edfaeb6..577d973f81 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/42] 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 0000000000..bf7bd5aef9 --- /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/42] 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 96eb4fa4c0..db23888c25 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/42] RTD cannot run multiple make targets --- Makefile | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Makefile b/Makefile index f045ce9dab..d267c1eddb 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/42] 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 136ce58e5c..0000000000 --- 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/42] 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 d267c1eddb..b76a84ff42 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 0a875a487a..0000000000 --- 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/42] 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 2044e5ca61..f6a5e854a3 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/42] 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 f6a5e854a3..d9f8670a26 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/42] 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 d9f8670a26..4c4dec8306 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/42] 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 4c4dec8306..c2fad13d0f 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/42] 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 c2fad13d0f..48fbda7bfc 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/42] 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 48fbda7bfc..0b21fe8c3b 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/42] 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 0b21fe8c3b..98ac47054c 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/42] Attempt to make plone.api importable to Sphinx --- Makefile | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Makefile b/Makefile index b76a84ff42..b52f75a868 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/42] 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 6a1a8b7718..d083f3b20b 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/42] 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 d083f3b20b..81f2a399ed 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/42] 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 81f2a399ed..6a1a8b7718 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 b52f75a868..154c9fa0ce 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/42] 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 154c9fa0ce..98e33474b1 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/42] 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 34ce02e2a9..76b1378d56 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 1e3d80c9df..38642ad336 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 24be3d4ff2..51d2a14f2c 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 e1b432dfef..1f328db5f8 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/42] 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 0000000000..e69de29bb2 From 35ab6fbf6a605ef580e87f24be60b9e9103976ba Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 18 May 2024 04:28:02 -0700 Subject: [PATCH 27/42] 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 4b7c5cccc9..0000000000 --- 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/42] 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 98ac47054c..31d297cfa6 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/42] 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 577d973f81..1cfa876f31 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/42] 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 db23888c25..96eb4fa4c0 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/42] 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 1cfa876f31..d6ad0cee8c 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/42] 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 d6ad0cee8c..791df1c2f7 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/42] 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 6a1a8b7718..16b5e05ebc 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 791df1c2f7..fe3c2db892 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/42] Use commands instead --- .readthedocs.yaml | 27 +++++++++++++-------------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 16b5e05ebc..8beeb58c45 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 From 487e0c173529f45790870b649c1622dc6571d707 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 14 Nov 2024 15:21:21 -0800 Subject: [PATCH 35/42] - Sort items in .gitignore - Remove obsolete documentation-custom.css file - Merge `conf.py` with 6.0 --- .gitignore | 6 +++--- docs/_static/documentation-custom.css | 0 docs/conf.py | 5 ++--- 3 files changed, 5 insertions(+), 6 deletions(-) delete mode 100644 docs/_static/documentation-custom.css diff --git a/.gitignore b/.gitignore index 7944bc77eb..a825459902 100644 --- a/.gitignore +++ b/.gitignore @@ -3,13 +3,13 @@ # Generated files /_build -/styles/Microsoft /share +/styles/Microsoft # symlinked from submodule -docs/volto -docs/plone.restapi docs/plone.api +docs/plone.restapi +docs/volto # editor files .vscode diff --git a/docs/_static/documentation-custom.css b/docs/_static/documentation-custom.css deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/conf.py b/docs/conf.py index 87038ce011..c438f70958 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -93,6 +93,7 @@ # Ignore github.com searches r"https://github.com/search", # Ignore rate limiting by github.com + r"https://github.com/collective/plone.app.locales/commits/master/", # 429 Client Error: Too Many Requests for url r"https://github.com/plone/volto/issues", r"https://github.com/plone/volto/pull", # Ignore other specific anchors @@ -100,7 +101,7 @@ r"https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors#Identifying_the_issue", r"https://docs.cypress.io/guides/references/migration-guide#Migrating-to-Cypress-version-10-0", # volto # Ignore unreliable sites - r"https://web.archive.org/", # volto + r"https://web.archive.org/", r"https://www.youtube.com/playlist", # volto, TODO remove after installing sphinxcontrib.youtube r"http://z3c.pt", # fluke where Sphinx interprets this as a URL ] @@ -279,7 +280,6 @@ "_static", # Last path wins. See https://github.com/plone/documentation/pull/1442 ] - # -- Options for autodoc ---------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration @@ -290,7 +290,6 @@ # Don't show class signature with the class' name. autodoc_class_signature = "separated" - # -- Options for MyST markdown conversion to HTML ----------------------------- # For more information see: From d9d66e60b00216ee0a87959a05da5e68d69e2efd Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 14 Nov 2024 15:22:38 -0800 Subject: [PATCH 36/42] - Remove obsolete custom.css file --- _docs/_static/custom.css | 0 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 _docs/_static/custom.css diff --git a/_docs/_static/custom.css b/_docs/_static/custom.css deleted file mode 100644 index e69de29bb2..0000000000 From 37d86f3f11c190815f9314b7593fd780c1c58d9d Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 14 Nov 2024 15:24:17 -0800 Subject: [PATCH 37/42] Update comments in linkcheckignore --- docs/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index c438f70958..6511945d01 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -92,8 +92,9 @@ r"https://github.com/.*#.*", # Ignore github.com searches r"https://github.com/search", + # Ignore GitHub 429 Client Error: Too Many Requests for url + r"https://github.com/collective/plone.app.locales/commits/master/", # Ignore rate limiting by github.com - r"https://github.com/collective/plone.app.locales/commits/master/", # 429 Client Error: Too Many Requests for url r"https://github.com/plone/volto/issues", r"https://github.com/plone/volto/pull", # Ignore other specific anchors From d54377f9d986f8b4e2a4b32abf4d7bf4a6ef094a Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 15 Nov 2024 04:50:56 -0800 Subject: [PATCH 38/42] plone.api must be installed to build its API docs. Remove symlinks in `distclean` allows its installation. --- Makefile | 27 ++++++++++++++++----------- docs/conf.py | 6 +++--- 2 files changed, 19 insertions(+), 14 deletions(-) diff --git a/Makefile b/Makefile index f48736ff94..90cefa23e8 100644 --- a/Makefile +++ b/Makefile @@ -30,8 +30,13 @@ clean: ## Clean docs build directory cd $(DOCS_DIR) && rm -rf $(BUILDDIR)/ .PHONY: distclean -distclean: clean ## Clean docs build directory and Python virtual environment +distclean: clean ## Clean docs build directory, Python virtual environment, and symlinks rm -rf venv + rm docs/plone.api + rm docs/plone.restapi + rm docs/volto + @echo + @echo "Cleaned docs build directory, Python virtual environment, and symlinks." venv/bin/python: ## Setup up Python virtual environment and install requirements python3 -m venv venv @@ -40,24 +45,24 @@ venv/bin/python: ## Setup up Python virtual environment and install requirement @echo @echo "Installation of requirements completed." -docs/plone.api: - git submodule init; \ - git submodule update; \ - venv/bin/pip install -e submodules/plone.api/"[test]"; \ +docs/plone.api: ## Setup plone.api docs + git submodule init + git submodule update + venv/bin/pip install -e submodules/plone.api/"[test]" ln -s ../submodules/plone.api/docs ./docs/plone.api @echo @echo "Documentation of plone.api initialized." -docs/plone.restapi: - git submodule init; \ - git submodule update; \ +docs/plone.restapi: ## Setup plone.restapi docs + git submodule init + git submodule update ln -s ../submodules/plone.restapi ./docs/plone.restapi @echo @echo "Documentation of plone.restapi initialized." -docs/volto: - git submodule init; \ - git submodule update; \ +docs/volto: ## Setup Volto docs + git submodule init + git submodule update ln -s ../submodules/volto/docs/source ./docs/volto @echo @echo "Documentation of volto initialized." diff --git a/docs/conf.py b/docs/conf.py index 6511945d01..14ccfa1bad 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -10,9 +10,9 @@ # 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("../submodules/plone.api/src")) +# import os +# import sys +# sys.path.insert(0, os.path.abspath(".")) # -- Project information ----------------------------------------------------- From 9aef4fc1af3af359b83218fedfcba21f4fefa8fc Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 15 Nov 2024 04:52:59 -0800 Subject: [PATCH 39/42] Tidy up conf.py --- docs/conf.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 14ccfa1bad..90a58b3cf5 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -276,11 +276,15 @@ html_extra_path = [ "robots.txt", ] +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". html_static_path = [ "volto/_static", "_static", # Last path wins. See https://github.com/plone/documentation/pull/1442 ] + # -- Options for autodoc ---------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration From 25e49839b8b46fea62c83a647189bedf301b45a8 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 15 Nov 2024 04:57:31 -0800 Subject: [PATCH 40/42] This file's content was migrated elsewhere --- docs/install/manage-add-ons-packages.md | 396 ------------------------ 1 file changed, 396 deletions(-) delete mode 100644 docs/install/manage-add-ons-packages.md diff --git a/docs/install/manage-add-ons-packages.md b/docs/install/manage-add-ons-packages.md deleted file mode 100644 index 1f328db5f8..0000000000 --- a/docs/install/manage-add-ons-packages.md +++ /dev/null @@ -1,396 +0,0 @@ ---- -myst: - html_meta: - "description": "Manage add-ons, packages, and processes" - "property=og:description": "Manage add-ons, packages, and processes" - "property=og:title": "Manage add-ons, packages, and processes" - "keywords": "Plone 6, manage, backend, add-ons, packages, processes, cookiecutter, Zope" ---- - - -(manage-add-ons-packages-and-processes-label)= - -# Manage add-ons and packages - -This chapter assumes you have previously followed {doc}`create-project`. -In this section, we discuss details of the installation process so that you can customize your Plone installation. -It also covers routine management tasks that a developer might perform. - - -(manage-installation-details-with-cookiecutter-label)= - -## Installation details with Cookiecutter - -{term}`Cookiecutter` creates projects from project templates. -The cookiecutter [`cookiecutter-plone-starter`](https://github.com/collective/cookiecutter-plone-starter/) creates a Plone project that you can install using {term}`Make`. -It generates files for installing and configuring both the frontend and backend. -For the backend, it uses [`cookiecutter-zope-instance`](https://github.com/plone/cookiecutter-zope-instance) to generate configuration files for a Zope WSGI instance. - - -(manage-configuration-with-cookiecutter-zope-instance-label)= - -## Configuration with `cookiecutter-zope-instance` - -You can configure your instance's options, including the following. - -- persistent storage: blobs, direct filestorage, relational database, ZEO, and so on -- ports -- threads -- cache -- debugging and profiling for development - -```{seealso} -For a complete list of features, usage, and options, read [`cookiecutter-zope-instance`'s `README.rst`](https://github.com/plone/cookiecutter-zope-instance#readme). -``` - - -(manage-plone-backend-packages-with-mxdev-label)= - -## Manage Plone backend packages with `mxdev` - -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`. - - -(manage-the-problem-with-pip-label)= - -### The problem with `pip` - -If you want to check out a Plone core package for development, or want to override the constraints of Plone, normally you would define constraints with a file {file}`constraints.txt` to tell `pip` to install a different version of a Plone package. - -``` -# constraints.txt with unresolvable version conflict --c https://dist.plone.org/release/{PLONE_BACKEND_PATCH_VERSION}/constraints.txt -plone.api>=2.0.0a3 -``` - -Unfortunately `pip` does not allow overriding constraints this way. -{term}`mxdev` solves this issue. - - -(manage-mxdev-to-the-rescue-label)= - -### `mxdev` to the rescue! - -`mxdev` resolves Plone constraints according to your needs for version pinning or source checkouts. -It reads its configuration file {file}`mx.ini`, and your {file}`requirements.txt` and {file}`constraints.txt` files. -Then it fetches the requirements and constraints of Plone. -Finally, it writes new combined requirements in {file}`requirements-mxdev.txt` and new constraints in {file}`constraints-mxdev.txt`. -Together these two files contain the combined requirements and constraints, but modified according to the configuration in {file}`mx.ini`. -The generated files indicate from where the constraints were fetched, and comments are added when a modification was necessary. - -`mxdev` does not run `pip` or install packages. -You must perform that step. - - -(manage-mxdev-usage-overview-label)= - -### `mxdev` usage overview - -The default set of files for `mxdev` is shown below. -They are located in the `backend` directory of your project. - -{file}`requirements.txt` - -```ini --c constraints.txt --e src/project_title - -zope.testrunner - -# Add required add-ons -# collective.easyform -``` - -{file}`constraints.txt` - -```ini --c https://dist.plone.org/release/{PLONE_BACKEND_PATCH_VERSION}/constraints.txt -``` - -{file}`mx.ini` - -```ini -; This is a mxdev configuration file -; it can be used to override versions of packages already defined in the -; constraints files and to add new packages from VCS like git. -; to learn more about mxdev visit https://pypi.org/project/mxdev/ - -[settings] -; example how to override a package version -; version-overrides = -; example.package==2.1.0a2 - -; example section to use packages from git -; [example.contenttype] -; url = https://github.com/collective/example.contenttype.git -; pushurl = git@github.com:collective/example.contenttype.git -; extras = test -; branch = feature-7 -``` - -You can edit these three files in your project as you need. -Then you can generate package requirements and constraints files, and then install those packages, with one command. - -```shell -make build-backend -``` - -`make build-backend` invokes `mxdev`, which generates the files {file}`requirements-mxdev.txt` and {file}`constraints-mxdev.txt`. -It then invokes `pip` to install packages with the new requirements file. - -To reload the packages, stop your Zope instance/Plone site with {kbd}`ctrl-c`, and start it with the following command. - -```shell -make start-backend -``` - -```{seealso} -See the [documentation of `mxdev` in its README.md](https://github.com/mxstack/mxdev/blob/main/README.md) for complete information. -``` - - -(manage-common-management-tasks-label)= - -## Common management tasks - -This section provides examples of common add-on and package management tasks. -For the examples, we will modify the default files from the previous section {ref}`manage-mxdev-usage-overview-label`. -We will also use Classic UI for the interface because some packages and add-ons have not yet been updated to work with the new frontend. - - -(manage-add-an-add-on)= - -### Add an add-on - -Add a line with the name of your add-on in `requirements.txt`. -This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/). - -``` -collective.easyform -``` - -Add it to {file}`instance.yaml` to let Zope know that this add-on should be loaded: - -```yaml -default_context: - zcml_package_includes: project_title, collective.easyform -``` - -Stop the backend with {kbd}`ctrl-c`. -Then apply your changes and start the backend. -You do not need to stop the frontend. - -```shell -make build-backend -make start-backend -``` - -In your web browser, and assuming you are currently logged in as `admin`, visit the URL http://localhost:8080/Plone/prefs_install_products_form. - -Then click the {guilabel}`Install` button next to your add-on to complete installation of the add-on. - -Some add-ons have configuration options. -To configure such add-ons, return to the {guilabel}`Site Setup` control panel. -At the bottom of the page, you should see the heading {guilabel}`Add-on Configuration`, and a control panel to configure the add-on that you just installed. - - -(manage-pin-the-version-of-an-add-on)= - -### Pin the version of an add-on - -Pin the version in {file}`constraints.txt`. - -``` -collective.easyform==3.1.0 -``` - -Add the add-on to {file}`requirements.txt`: - -``` -collective.easyform -``` - -Add it to {file}`instance.yaml` to let Zope know that this add-on should be loaded: - -```yaml -default_context: - zcml_package_includes: project_title, collective.easyform -``` - -Stop the backend with {kbd}`ctrl-c`. -Then apply your changes and start the backend. - -```shell -make build-backend -make start-backend -``` - -In your web browser, and assuming you are currently logged in as `admin`, visit the URL http://localhost:8080/Plone/prefs_install_products_form. -An upgrade step might need to be performed in the Plone control panel. -Follow the upgrade information, if present. -Else click the {guilabel}`Install` button to complete installation of the add-on. - - -(manage-check-out-an-add-on)= - -### Check out an add-on - -Add the add-on in {file}`requirements.txt`: - -``` -collective.easyform -``` - -In {file}`mx.ini`, specify the information to check out the add-on: - -```ini -[collective.easyform] -url=git@github.com:collective/collective.easyform.git -branch=dev-branch-name -extras=test -``` - -Add it to {file}`instance.yaml` to let Zope know that this add-on should be loaded: - -```yaml -default_context: - zcml_package_includes: project_title, collective.easyform -``` - -Stop the backend with {kbd}`ctrl-c`. -Then apply your changes and start the backend. - -```shell -make build-backend -make start-backend -``` - -In your web browser, and assuming you are currently logged in as `admin`, visit the URL http://localhost:8080/Plone/prefs_install_products_form. -An upgrade step might need to be performed in the Plone control panel. -Follow the upgrade information, if present. -Else click the {guilabel}`Install` button to complete installation of the add-on. - - -(manage-pin-the-version-of-a-plone-package-against-constraints-label)= - -### Pin the version of a Plone package against constraints - -A version can **not** be pinned in `constraints.txt` when the package is mentioned in the constraints of Plone. -Any other package version could be pinned in `constraints.txt`. - -Pin the version of a Plone package in {file}`mx.ini`: - -```ini -[settings] -# constraints of Plone packages -version-overrides = - plone.api>=2.0.0a3 -``` - -Apply your changes and restart backend: - -```shell -make build-backend -make start-backend -``` - -In your web browser, and assuming you are currently logged in as `admin`, visit the URL http://localhost:8080/Plone/prefs_install_products_form. -An upgrade step might need to be performed in the Plone control panel. -Follow the upgrade information, if present. - - -(manage-checkout-a-plone-package-label)= - -### Check out a Plone package - -This section covers how to check out a Plone Core package for development. - -Add the Plone package you want to check out in {file}`mx.ini`. - -```ini -[plone.restapi] -url = git@github.com:plone/plone.restapi.git -branch = main -extras = test -``` - -Stop the backend with {kbd}`ctrl-c`. -Then apply your changes and start the backend. - -```shell -make build-backend -make start-backend -``` - -In your web browser, and assuming you are currently logged in as `admin`, visit the URL http://localhost:8080/Plone/prefs_install_products_form. -An upgrade step might need to be performed in the Plone control panel. -Follow the upgrade information, if present. - - -(manage-build-and-start-your-instance-label)= - -### Build and start your instance - -Whenever you make changes to your backend configuration—for example, install an add-on, or override a Plone core package—then a build and restart is needed. -First stop your Zope instance/Plone site with {kbd}`ctrl-c`. -Then build and run the Plone backend. - -```shell -make build-backend -make start-backend -``` - -In a web browser, visit http://localhost:8080/ to see that Plone is running. - -Your instance is running in the foreground. - - -(manage-installation-details-label)= - -## Backend installation details - -The `Makefile` at the root of your project invokes commands in `backend/Makefile`. -Here are excerpts from `backend/Makefile` to show details of the `make build-backend` command. - -```makefile -bin/pip: - @echo "$(GREEN)==> Setup Virtual Env$(RESET)" - python3 -m venv . - bin/pip install -U "pip" "wheel" "cookiecutter" "mxdev" - -instance/etc/zope.ini: bin/pip - @echo "$(GREEN)==> Install Plone and create instance$(RESET)" - bin/cookiecutter -f --no-input --config-file instance.yaml https://github.com/plone/cookiecutter-zope-instance - mkdir -p var/{filestorage,blobstorage,cache,log} - -# ... - -.PHONY: build-dev -build-dev: instance/etc/zope.ini ## pip install Plone packages - @echo "$(GREEN)==> Setup Build$(RESET)" - bin/mxdev -c mx.ini - bin/pip install -r requirements-mxdev.txt -``` - -The command `make build-backend`: - -- Invokes the target `build-dev` target in `backend/Makefile`. -- This invokes the target `instance/etc/zope.ini`. -- This invokes the target `bin/pip`. - - - This creates a `Python` virtual environment if one does not exist. - - It installs and upgrades Python package management tools in that virtual environment. - -- Returning to the target `instance/etc/zope.ini`: - - - This creates or updates the Zope configuration from its `instance.yaml` file using `cookiecutter-zope-instance`. - - Creates specified directories, if they do not exist. - -- Returning to the target `build-dev`: - - - This generates the `mxdev` files as described above in {ref}`manage-mxdev-usage-overview-label`. - - Installs Plone core packages and add-ons from the files generated by `mxdev`. - -You can configure your Zope instance as described in the section {ref}`manage-common-management-tasks-label`. From bc72bcdfbb6676c978a2c94576686b7ccc84bbfc Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 17 Nov 2024 03:42:43 -0800 Subject: [PATCH 41/42] Disable Edit this page, and add comments explaining that it does not support multiple repositories --- docs/conf.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 90a58b3cf5..06204b0be8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -249,15 +249,16 @@ "json_url": "https://6.docs.plone.org/_static/switcher.json", "version_match": version, }, - "use_edit_page_button": True, + "use_edit_page_button": False, # This option does not support multiple repositories. "use_issues_button": True, "use_repository_button": True, } # 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", -} +# used by `use_edit_page_button`, but it does not support multiple repositories +# html_context = { +# "edit_page_url_template": "https://6.docs.plone.org/contributing/documentation/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 From 3a417d5ee559eebb655db2496a559ad69ec68804 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 17 Nov 2024 05:25:33 -0800 Subject: [PATCH 42/42] Update documentation for build pull request previews. --- docs/contributing/documentation/admins.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/contributing/documentation/admins.md b/docs/contributing/documentation/admins.md index ac0c177f15..9cbad11978 100644 --- a/docs/contributing/documentation/admins.md +++ b/docs/contributing/documentation/admins.md @@ -96,11 +96,11 @@ The following are example files that you can use to configure your project for p - [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-dev.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 `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. +- [Plone Sphinx Theme `.readthedocs.yaml`](https://github.com/plone/plone-sphinx-theme/blob/main/.readthedocs.yaml) specifies the configuration and Makefile command that Read the Docs uses 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 and there are changes to the documentation files. + You might need to adjust the `paths` and `project-slug` for your documentation. ### Import your project @@ -113,9 +113,10 @@ After logging in to your Read the Docs account, you can import your project. 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. + Read the Docs will redirect you to the project details, and start building the docs, but you don't need to wait. +1. Click the {guilabel}`Settings` button. +1. Scroll to the end of the page and check the box for {guilabel}`Build pull requests for this project`. +1. Click {guilabel}`Save` to save the new setting. ### Search engine indexing @@ -138,10 +139,10 @@ cp source-path/block-robots.txt docs-root-path/robots.txt ``` ```{seealso} +- [`robots.txt` support](https://docs.readthedocs.io/en/stable/reference/robots.html) - [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) ```