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/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/backend/upgrading/version-specific-migration/upgrade-to-60.md b/docs/backend/upgrading/version-specific-migration/upgrade-to-60.md index 51651cf6a1..279e512159 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/conf.py b/docs/conf.py index 7de8f71537..06204b0be8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -33,6 +33,7 @@ # The full version, including alpha/beta/rc tags. release = "6" + # -- General configuration ---------------------------------------------------- # Add any paths that contain templates here, relative to this directory. @@ -85,11 +86,14 @@ # Ignore pages that require authentication r"https://github.com/orgs/plone/teams/", # requires auth r"https://github.com/plone/documentation/issues/new", # requires auth + r"https://github.com/plone/volto/issues/new/choose", # requires auth r"https://opensource.org/", # requires auth # Ignore github.com pages with anchors 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/plone/volto/issues", r"https://github.com/plone/volto/pull", @@ -98,11 +102,8 @@ 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://chromewebstore.google.com/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi", # TODO retest with latest Sphinx when upgrading theme. chromewebstore recently changed its URL and has "too many redirects". - # r"https://chromewebstore.google.com/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd", # TODO retest with latest Sphinx when upgrading theme. chromewebstore recently changed its URL and has "too many redirects". - # r"https://stackoverflow.com", # volto and documentation # TODO retest with latest Sphinx. - r"https://web.archive.org/", # volto -# r"https://www.youtube.com/playlist", # volto, TODO remove after installing sphinxcontrib.youtube + 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 ] linkcheck_allowed_redirects = { # TODO: Confirm usage of linkcheck_allowed_redirects @@ -241,22 +242,23 @@ "primary_sidebar_end": [ "version-switcher", ], - "repository_branch": "main", + "repository_branch": "6.0", "repository_url": "https://github.com/plone/documentation", "search_bar_text": "Search", "switcher": { "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 @@ -275,7 +277,6 @@ 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". @@ -295,16 +296,7 @@ # Don't show class signature with the class' name. autodoc_class_signature = "separated" - -# -- 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}" -sitemap_filename = "sitemap-custom.xml" - -# -- Options for myST markdown conversion to html ----------------------------- +# -- Options for MyST markdown conversion to HTML ----------------------------- # For more information see: # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html @@ -328,6 +320,7 @@ "fawrench": '', } + # -- Intersphinx configuration ---------------------------------- # This extension can generate automatic links to the documentation of objects @@ -359,7 +352,7 @@ # -- Mermaid configuration ---------------------------------- -# mermaid_version = "10.9.1" +mermaid_version = "11.2.0" # -- OpenGraph configuration ---------------------------------- @@ -374,12 +367,13 @@ ] -# -- 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" @@ -396,6 +390,15 @@ } +# -- 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}" +sitemap_filename = "sitemap-custom.xml" + + # -- Options for HTML help output ------------------------------------------------- # Output file base name for HTML help builder. @@ -411,7 +414,7 @@ "index", "PloneDocumentation.tex", "Plone Documentation", - "The Plone community", + "Plone community", "manual", ), ] @@ -421,6 +424,7 @@ latex_logo = "_static/logo_2x.png" # -- Configuration for source_replacements extension ----------------------- + # An extension that allows replacements for code blocks that # are not supported in `rst_epilog` or other substitutions. # https://stackoverflow.com/a/56328457/2214933 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) ``` 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 84ad3a0442..686d7cd918 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -167,7 +167,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/requirements-initial.txt b/requirements-initial.txt index 454722d5b1..af9088a5de 100644 --- a/requirements-initial.txt +++ b/requirements-initial.txt @@ -1,3 +1,4 @@ +# requirements-initial.txt # From https://dist.plone.org/release/6-latest/constraints.txt pip==24.0 setuptools==71.0.0 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 diff --git a/requirements.txt b/requirements.txt index 894d3a4a44..ce4856121e 100644 --- a/requirements.txt +++ b/requirements.txt @@ -3,13 +3,13 @@ linkify-it-py plone-sphinx-theme sphinx-autobuild sphinx-copybutton -sphinx-design +sphinx-design # Documentation only sphinx-examples sphinx-notfound-page # Documentation only sphinx-reredirects sphinx-sitemap -sphinxcontrib.httpdomain -sphinxcontrib.httpexample +sphinxcontrib.httpdomain # plone.restapi +sphinxcontrib.httpexample # plone.restapi sphinxcontrib-video sphinxext-opengraph sphinxcontrib.mermaid