Administrators Guide

This guide is for administrators of Plone Documentation. It covers automated deployments, hosting, automated testing, previewing, and importing external package documentation into Plone Documentation.

Importing external docs and converting to MyST

This section describes how to import external projects and convert their docs to MyST. We did this for plone.app.dexterity and several other projects.

1. Create a new branch using the name of the project.

2. Install rst-to-myst.

   bin/pip install "rst-to-myst[sphinx]"
   

3. Clone the project repository to the root of plone/documentation.

4. Delete any non-documentation files from the clone.

5. Move the documentation files and subfolders to the root of the clone, retaining the documentation structure.

6. Convert the reStructuredText documentation files to MyST. The example commands below assume that there are files at the root of the clone and in one sub-level of nested directories. For deeper nesting, insert globbing syntax for each sub-level as **/

   bin/rst2myst convert -R project/*.rst
   bin/rst2myst convert -R project/**/*.rst
   

7. Add HTML meta data to the converted files.

   cd project
   ../bin/python ../docs/addMetaData.py
   

8. Optionally clean up any MyST syntax.

9. Commit and push your branch to GitHub and create a pull request.

Importing external docs with submodules

To add an external package to Plone Documentation, we use git submodules. We did this with Volto documentation. Your package must be available under the Plone GitHub organization.

Inside the repository plone/documentation, add a git submodule that points to your project.

git submodule add git@github.com:plone/my_package.git submodules/my_package

Add a target docs/my_package in Makefile, then add docs/my_package to the deps target, following volto as a pattern. You might need to adjust the paths to your package's documentation after it is cloned.

To complete setup, generate a symlink to your project's docs, and build the docs, use a single command.

make html

To make it easier for other contributors to work with your project, update the following files, using volto as a model.

• Add it to the documentation section Editing external package documentation.

• Add the symlink docs/my_package to .gitignore.

• Optionally set a branch to work on in .gitmodules.

Commit and push your changes to a remote, and submit a pull request against plone/documentation@6.0.

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.

1. Visit Team Overview.

2. Click Add a new site and select Import an existing project.

3. Click Deploy with GitHub.

4. Select plone for the GitHub organization.

5. Click Configure Netlify on GitHub.

6. Select the organization to where you want to install Netlify.

7. Click Select repositories and select the repository that you want to add.

8. Click Update access.

9. Netlify sends an email to members of the email group admins at plone.org, who need to review and approve the request. However the email doesn't specify the repository, and admins will not know what to do. You must send email to that group, including in your request the organization and repository, such as plone/volto.

10. The admin must login to GitHub as an organization owner, then navigate to the requested repository's Settings. [What else Admin person?]

11. The admin replies to the requestor, letting them know the request was approved.

From here you need to update your repository to work with Netlify. For an example, see the following files.

• Volto Makefile, specifically the netlify section. This will become the command used to build docs on Netlify.

• Volto requirements-docs.txt specifies the requirements to build the docs.

• Volto netlify.toml specifies when to build the docs, specifically only when there are changes to documentation files.

Finally you need to configure your site in Netlify. You may have done some of these steps earlier, but you might need to refine them. The critical pieces are the following.

1. From the dashboard, select the site to edit it.

2. Click Site configuration.

3. One time only, under General > Site details click Change site name. A modal dialog appears. Enter the site name using the pattern ORGANIZATION_NAME-REPOSITORY_NAME. For example, plone-components. Click Save.

4. Under Build & deploy > Continuous deployment, scroll to Build settings, and click Configure, then enter the following values.

   • Base directory: /

   • Package directory: /

   • Build command: make netlify. This is the command you would define in your Makefile.

   • Publish directory: _build/html. This is where the make command will output files.

   • Finally click Save.

5. Under Build & deploy > Continuous deployment, scroll to Branches and deploy contexts, and click Configure, then enter appropriate values.