Skip to content

Commit 90d6a05

Browse files
stevepiercystevepiercy
authored
Merge pull request #1672 from plone/rtd-pull-request-preview
Use RTD for pull request previews
2 parents 197a955 + a8fd30b commit 90d6a05

File tree

4 files changed

+169
-54
lines changed

4 files changed

+169
-54
lines changed

‎.github/workflows/rtd-pr-preview.yml

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# .github/workflows/rtd-pr-preview.yml
2+
name: readthedocs/actions
3+
on:
4+
pull_request_target:
5+
types:
6+
- opened
7+
# Execute this action only on PRs that touch
8+
# documentation files.
9+
# paths:
10+
# - "docs/**"
11+
12+
permissions:
13+
pull-requests: write
14+
15+
jobs:
16+
documentation-links:
17+
runs-on: ubuntu-latest
18+
steps:
19+
- uses: readthedocs/actions/preview@v1
20+
with:
21+
project-slug: "plone6"
22+
single-version: "true"

‎.readthedocs.yaml

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# .readthedocs.yaml
2+
# Read the Docs configuration file
3+
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
4+
5+
# Required
6+
version: 2
7+
8+
# Set the OS, Python version and other tools you might need
9+
build:
10+
os: ubuntu-22.04
11+
tools:
12+
python: "3.12"
13+
commands:
14+
# Cancel building pull requests when there aren't changes in the docs directory or YAML file.
15+
# You can add any other files or directories that you'd like here as well,
16+
# like your docs requirements file, or other files that will change your docs build.
17+
#
18+
# If there are no changes (git diff exits with 0) we force the command to return with 183.
19+
# This is a special exit code on Read the Docs that will cancel the build immediately.
20+
- |
21+
if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- docs/ .readthedocs.yaml requirements-initial.txt requirements.txt;
22+
then
23+
exit 183;
24+
fi
25+
- make rtd-pr-preview

‎Makefile

+6-7
Original file line numberDiff line numberDiff line change
@@ -224,18 +224,17 @@ livehtml: deps ## Rebuild Sphinx documentation on changes, with live-reload in
224224
--port 8050 \
225225
-b html . "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
226226

227-
.PHONY: netlify
228-
netlify:
227+
.PHONY: rtd-pr-preview
228+
rtd-pr-preview: ## Build pull request preview on Read the Docs
229229
pip install -r requirements-initial.txt
230230
pip install -r requirements.txt
231-
pip install -r requirements-netlify.txt
232-
git submodule init; \
233-
git submodule update; \
234-
pip install -e submodules/plone.api[test]; \
231+
git submodule init
232+
git submodule update
233+
pip install -e submodules/plone.api[test]
235234
ln -s ../submodules/volto/docs/source ./docs/volto
236235
ln -s ../submodules/plone.restapi ./docs/plone.restapi
237236
ln -s ../submodules/plone.api/docs ./docs/plone.api
238-
cd $(DOCS_DIR) && sphinx-build -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html && cp ./netlify_robots.txt $(BUILDDIR)/html/robots.txt
237+
cd $(DOCS_DIR) && sphinx-build -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/
239238

240239
.PHONY: storybook
241240
storybook:

‎docs/contributing/documentation/admins.md

+116-47
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ myst:
44
"description": "Administrators' guide to writing Plone Documentation. It covers automated deployments, hosting, automated testing, previewing, and importing external package documentation into Plone Documentation."
55
"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."
66
"property=og:title": "Administrators Guide"
7-
"keywords": "Plone, Documentation, automated deployments, hosting, automated testing, importing external packages"
7+
"keywords": "Plone, Documentation, automated deployments, hosting, automated testing, importing external packages, preview, build, pull request"
88
---
99

1010
(administrators-guide-label)=
@@ -84,49 +84,118 @@ To make it easier for other contributors to work with your project, update the f
8484
Commit and push your changes to a remote, and submit a pull request against [`plone/[email protected]`](https://github.com/plone/documentation/compare).
8585

8686

87-
## Add a project to Netlify
88-
89-
To add a new site to Netlify to preview built documentation or storybooks, you need to add a new site to Netlify.
90-
91-
1. Visit [Team Overview](https://app.netlify.com/teams/plone/overview).
92-
1. Click {guilabel}`Add a new site` and select {guilabel}`Import an existing project`.
93-
1. Click {guilabel}`Deploy with GitHub`.
94-
1. Select {guilabel}`plone` for the GitHub organization.
95-
1. Click {guilabel}`Configure Netlify on GitHub`.
96-
1. Select the organization to where you want to install Netlify.
97-
1. Click {guilabel}`Select repositories` and select the repository that you want to add.
98-
1. Click {guilabel}`Update access`.
99-
1. Netlify sends an email to members of the email group `admins` at `plone.org`, who need to review and approve the request.
100-
However the email doesn't specify the repository, and admins will not know what to do.
101-
You must send email to that group, including in your request the organization and repository, such as `plone/volto`.
102-
1. The admin must login to GitHub as an organization owner, then navigate to the requested repository's {guilabel}`Settings`. [What else Admin person?]
103-
1. The admin replies to the requestor, letting them know the request was approved.
104-
105-
From here you need to update your repository to work with Netlify.
106-
For an example, see the following files.
107-
108-
- [Volto `Makefile`](https://github.com/plone/volto/blob/main/Makefile), specifically the `netlify` section.
109-
This will become the command used to build docs on Netlify.
110-
- [Volto `requirements-docs.txt`](https://github.com/plone/volto/blob/main/requirements-docs.txt) specifies the requirements to build the docs.
111-
- [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.
112-
113-
Finally you need to configure your site in Netlify.
114-
You may have done some of these steps earlier, but you might need to refine them.
115-
The critical pieces are the following.
116-
117-
1. From the dashboard, select the site to edit it.
118-
1. Click {guilabel}`Site configuration`.
119-
1. One time only, under {guilabel}`General > Site details` click {guilabel}`Change site name`.
120-
A modal dialog appears.
121-
Enter the site name using the pattern `ORGANIZATION_NAME-REPOSITORY_NAME`.
122-
For example, `plone-components`.
123-
Click {guilabel}`Save`.
124-
1. Under {guilabel}`Build & deploy > Continuous deployment`, scroll to {guilabel}`Build settings`, and click {guilabel}`Configure`, then enter the following values.
125-
- {guilabel}`Base directory`: `/`
126-
- {guilabel}`Package directory`: `/`
127-
- {guilabel}`Build command`: `make netlify`.
128-
This is the command you would define in your `Makefile`.
129-
- {guilabel}`Publish directory`: `_build/html`.
130-
This is where the `make` command will output files.
131-
- Finally click {guilabel}`Save`.
132-
1. Under {guilabel}`Build & deploy > Continuous deployment`, scroll to {guilabel}`Branches and deploy contexts`, and click {guilabel}`Configure`, then enter appropriate values.
87+
## Pull request preview builds
88+
89+
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.
90+
You also need an account on Read the Docs and have write access to the repository.
91+
92+
93+
### Configuration files
94+
95+
The following are example files that you can use to configure your project for pull request previews on Read the Docs.
96+
97+
- [Plone Sphinx Theme `Makefile`](https://github.com/plone/plone-sphinx-theme/blob/main/Makefile), specifically the `rtd-pr-preview` section.
98+
This is the command to use to build documentation previews on Read the Docs.
99+
- [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.
100+
- [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.
101+
- [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.
102+
- [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.
103+
- [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.
104+
You might need to adjust the branch name, paths, and files to check for changes.
105+
106+
107+
### Import your project
108+
109+
After logging in to your Read the Docs account, you can import your project.
110+
111+
1. Click {guilabel}`Add project`.
112+
1. For {guilabel}`Repository name`, enter the GitHub organization, a forward slash, and the repository to import, for example, `plone/volto`.
113+
1. Click {guilabel}`Continue`.
114+
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`.
115+
The defaults are usually accurate.
116+
1. Click {guilabel}`Next`.
117+
1. A sample `.readthedocs.yaml` file is suggested, if you have not already added one.
118+
1. Click {guilabel}`Finish`.
119+
Read the Docs will redirect you to the project details, and start building the docs.
120+
121+
122+
### Search engine indexing
123+
124+
Many Plone projects currently self-host their official documentation at {doc}`/index`.
125+
These projects get indexed by search engines.
126+
127+
For pull request previews, unsupported branches or versions, or other situations, you most likely do not want search engines to index your documentation.
128+
Your options include the following.
129+
130+
- Deactivate your build
131+
- Hide your build
132+
- Create a custom {file}`robots.txt` file to discourage, but not absolutely prevent, search engine indexing
133+
134+
For the last option, you can configure Sphinx to copy the {file}`robots.txt` file.
135+
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.
136+
137+
```shell
138+
cp source-path/block-robots.txt docs-root-path/robots.txt
139+
```
140+
141+
```{seealso}
142+
- [Automation rules](https://docs.readthedocs.io/en/stable/automation-rules.html)
143+
- [Versions](https://docs.readthedocs.io/en/stable/versions.html)
144+
- [Managing versions automatically](https://docs.readthedocs.io/en/stable/guides/automation-rules.html)
145+
- [`robots.txt` support](https://docs.readthedocs.io/en/stable/reference/robots.html)
146+
```
147+
148+
149+
### Cancel builds programmatically
150+
151+
You might want to cancel a build programmatically when certain conditions are met.
152+
You can do this through your {file}`.readthedocs.yaml` file.
153+
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).
154+
155+
156+
#### Build only on changes
157+
158+
When there are no changes to documentation, it is not necessary to build it.
159+
You can save time and energy by programmatically building documentation only when it changes.
160+
161+
In your {file}`.readthedocs.yaml` file, you could use the following example.
162+
163+
```yaml
164+
version: 2
165+
build:
166+
os: "ubuntu-22.04"
167+
tools:
168+
python: "3.12"
169+
jobs:
170+
post_checkout:
171+
# Cancel building pull requests when there aren't changes in the docs directory or YAML file.
172+
# You can add any other files or directories that you'd like here as well,
173+
# like your docs requirements file, or other files that will change your docs build.
174+
#
175+
# If there are no changes (git diff exits with 0) we force the command to return with 183.
176+
# This is a special exit code on Read the Docs that will cancel the build immediately.
177+
- |
178+
if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- docs/ .readthedocs.yaml requirements-initial.txt requirements.txt;
179+
then
180+
exit 183;
181+
fi
182+
```
183+
184+
185+
#### Cancel builds on a branch
186+
187+
If you have pull request preview builds enabled, any pull request to any branch will trigger a build.
188+
If you do not want to build documentation on a specific branch, you can cancel a build programmatically through your {file}`.readthedocs.yaml` file.
189+
190+
```yaml
191+
version: 2
192+
build:
193+
os: "ubuntu-22.04"
194+
tools:
195+
python: "3.12"
196+
jobs:
197+
post_checkout:
198+
# Cancel the Read the Docs build
199+
# https://docs.readthedocs.io/en/stable/build-customization.html#cancel-build-based-on-a-condition
200+
- exit 183;
201+
```

0 commit comments

Comments
 (0)