Skip to content

Add documentation for how to administer Read the Docs for documentation and update Plone Sphinx Theme configuration #1667

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 48 commits into from
Nov 18, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
48 commits
Select commit Hold shift + click to select a range
35fb31e
Add documentation for how to administer Read the Docs for documentation
stevepiercy May 15, 2024
d69b493
Remove subprojects mention
stevepiercy May 16, 2024
a71e224
Remove Netlify configuration
stevepiercy May 16, 2024
cc70b0e
Merge branch '6.0' into pull-request-preview
stevepiercy May 16, 2024
03335af
Update requirements files
stevepiercy May 16, 2024
25a9e76
Remove netlify.toml
stevepiercy May 16, 2024
79e77be
Add RTD configuration
stevepiercy May 16, 2024
cb5eb31
Update conf.py for new theme
stevepiercy May 16, 2024
9607018
Add configuration for pull request previews on RTD
stevepiercy May 16, 2024
c23aa55
Try using deps to pull in submodules and create symlinks
stevepiercy May 16, 2024
6e48d39
RTD cannot run multiple make targets
stevepiercy May 16, 2024
f4d0076
Remove obsolete Sphinx template `_templates/sections/header-article.h…
stevepiercy May 16, 2024
36c78cb
Purge Netlify
stevepiercy May 17, 2024
4344e0e
Attempt to make plone.api importable to Sphinx
stevepiercy May 17, 2024
bef89c4
Attempt to make plone.api importable to Sphinx
stevepiercy May 17, 2024
dbe975a
Attempt to make plone.api importable to Sphinx
stevepiercy May 17, 2024
37a8ed4
Attempt to make plone.api importable to Sphinx
stevepiercy May 17, 2024
14bb19e
Attempt to make plone.api importable to Sphinx
stevepiercy May 17, 2024
5aceb91
Attempt to make plone.api importable to Sphinx
stevepiercy May 17, 2024
f28a966
Attempt to make plone.api importable to Sphinx
stevepiercy May 17, 2024
77a4299
Attempt to make plone.api importable to Sphinx
stevepiercy May 17, 2024
103ab2e
Attempt to make plone.api importable to Sphinx by bypassing Makefile
stevepiercy May 17, 2024
be920d4
Attempt to make plone.api importable to Sphinx by bypassing Makefile
stevepiercy May 17, 2024
bd5c377
Attempt to make plone.api importable to Sphinx by using its system Py…
stevepiercy May 17, 2024
0c67dd2
Attempt to make plone.api importable to Sphinx by using its system Py…
stevepiercy May 17, 2024
0a4968c
Fix link references
stevepiercy May 17, 2024
d5d6974
Relocate static files
stevepiercy May 18, 2024
35ab6fb
Purge Netlify
stevepiercy May 18, 2024
d99838e
Clean up `conf.py`
stevepiercy May 18, 2024
ada6b81
Fix link
stevepiercy May 19, 2024
097546f
Revert "Try using deps to pull in submodules and create symlinks"
stevepiercy May 20, 2024
9dc849d
Merge branch '6.0' into pull-request-preview
stevepiercy May 20, 2024
35372cf
Rename headings and improve flow
stevepiercy May 21, 2024
df9a0ee
Rewrite search engine indexing section
stevepiercy May 21, 2024
06ffcc1
Merge branch '6.0' into pull-request-preview
stevepiercy May 21, 2024
84c0ff0
Update configuration to build only on changes to docs files
stevepiercy May 21, 2024
ca19f1c
Use commands instead
stevepiercy May 21, 2024
28b9df9
Merge branch '6.0' into pull-request-preview
stevepiercy May 21, 2024
e566e06
Merge branch '6.0' into pull-request-preview
stevepiercy Jun 20, 2024
0d89f9d
Merge branch '6.0' into pull-request-preview
stevepiercy Nov 14, 2024
487e0c1
- Sort items in .gitignore
stevepiercy Nov 14, 2024
d9d66e6
- Remove obsolete custom.css file
stevepiercy Nov 14, 2024
37d86f3
Update comments in linkcheckignore
stevepiercy Nov 14, 2024
d54377f
plone.api must be installed to build its API docs. Remove symlinks in…
stevepiercy Nov 15, 2024
9aef4fc
Tidy up conf.py
stevepiercy Nov 15, 2024
25e4983
This file's content was migrated elsewhere
stevepiercy Nov 15, 2024
bc72bcd
Disable Edit this page, and add comments explaining that it does not …
stevepiercy Nov 17, 2024
3a417d5
Update documentation for build pull request previews.
stevepiercy Nov 17, 2024
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -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
27 changes: 16 additions & 11 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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."
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 <theming_plone_5/index>`:
The training documentation lists {doc}`three possible theming strategies <training-2022:theming_plone_5/index>`:

- Create a theme based on Barceloneta.
- Create a theme from scratch.
Expand Down
54 changes: 29 additions & 25 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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",
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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".
Expand All @@ -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
Expand All @@ -328,6 +320,7 @@
"fawrench": '<span class="fa fa-wrench" style="font-size: 1.6em;"></span>',
}


# -- Intersphinx configuration ----------------------------------

# This extension can generate automatic links to the documentation of objects
Expand Down Expand Up @@ -359,7 +352,7 @@


# -- Mermaid configuration ----------------------------------
# mermaid_version = "10.9.1"
mermaid_version = "11.2.0"


# -- OpenGraph configuration ----------------------------------
Expand All @@ -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"
Expand All @@ -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.
Expand All @@ -411,7 +414,7 @@
"index",
"PloneDocumentation.tex",
"Plone Documentation",
"The Plone community",
"Plone community",
"manual",
),
]
Expand All @@ -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
Expand Down
17 changes: 9 additions & 8 deletions docs/contributing/documentation/admins.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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)
```


Expand Down
4 changes: 2 additions & 2 deletions docs/contributing/documentation/themes-and-extensions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/).
2 changes: 1 addition & 1 deletion docs/contributing/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
1 change: 1 addition & 0 deletions requirements-initial.txt
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
# requirements-initial.txt
# From https://dist.plone.org/release/6-latest/constraints.txt
pip==24.0
setuptools==71.0.0
Expand Down
1 change: 0 additions & 1 deletion requirements-netlify.txt

This file was deleted.

6 changes: 3 additions & 3 deletions requirements.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down