Add documentation for how to administer Read the Docs for documentation

Author: stevepiercy

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

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/[email protected]`](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.