diff --git a/.gitignore b/.gitignore index 7944bc77e..a82545990 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 f48736ff9..90cefa23e 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 51651cf6a..279e51215 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 7de8f7153..90a58b3cf 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,7 +242,7 @@ "primary_sidebar_end": [ "version-switcher", ], - "repository_branch": "main", + "repository_branch": "6.0", "repository_url": "https://github.com/plone/documentation", "search_bar_text": "Search", "switcher": { @@ -275,7 +276,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 +295,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 +319,7 @@ "fawrench": '', } + # -- Intersphinx configuration ---------------------------------- # This extension can generate automatic links to the documentation of objects @@ -359,7 +351,7 @@ # -- Mermaid configuration ---------------------------------- -# mermaid_version = "10.9.1" +mermaid_version = "11.2.0" # -- OpenGraph configuration ---------------------------------- @@ -374,12 +366,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 +389,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 +413,7 @@ "index", "PloneDocumentation.tex", "Plone Documentation", - "The Plone community", + "Plone community", "manual", ), ] @@ -421,6 +423,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/themes-and-extensions.md b/docs/contributing/documentation/themes-and-extensions.md index 1e3d80c9d..38642ad33 100644 --- a/docs/contributing/documentation/themes-and-extensions.md +++ b/docs/contributing/documentation/themes-and-extensions.md @@ -58,9 +58,9 @@ We use several MyST and Sphinx extensions to enhance the presentation of Plone d - [`sphinx_reredirects`](https://documatt.com/sphinx-reredirects/) handles redirects for moved pages. - [`sphinx_sitemap`](https://pypi.org/project/sphinx-sitemap/) generates multiversion and multilanguage [sitemaps.org](https://www.sitemaps.org/protocol.html) compliant sitemaps. - [`sphinxcontrib.httpdomain`](https://sphinxcontrib-httpdomain.readthedocs.io/en/stable/) provides a Sphinx domain for describing HTTP APIs. - It is used by Plone's {doc}`plone.restapi/docs/source/index`. + It is used by Plone's {doc}`/plone.restapi/docs/source/index`. - [`sphinxcontrib.httpexample`](https://sphinxcontrib-httpexample.readthedocs.io/en/latest/) enhances `sphinxcontrib-httpdomain` by generating RESTful HTTP API call examples for different tools from a single HTTP request example. Supported tools include [curl](https://curl.se/), [wget](https://www.gnu.org/software/wget/), [httpie](https://httpie.io/), and [python-requests](https://requests.readthedocs.io/en/latest/). - It is used by Plone's {doc}`plone.restapi/docs/source/index`. + It is used by Plone's {doc}`/plone.restapi/docs/source/index`. - [`sphinxcontrib.video`](https://pypi.org/project/sphinxcontrib-video/) allows you to embed local videos as defined by the HTML5 standard. - [`sphinxext.opengraph`](https://pypi.org/project/sphinxext-opengraph/) generates [OpenGraph metadata](https://ogp.me/). diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 84ad3a044..686d7cd91 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 454722d5b..af9088a5d 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 4b7c5cccc..000000000 --- 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 894d3a4a4..ce4856121 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