Administrators Guide
Contents
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.
Create a new branch using the name of the project.
Install rst-to-myst.
bin/pip install "rst-to-myst[sphinx]"
Clone the project repository to the root of
plone/documentation
.Delete any non-documentation files from the clone.
Move the documentation files and subfolders to the root of the clone, retaining the documentation structure.
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
Add HTML meta data to the converted files.
cd project ../bin/python ../docs/addMetaData.py
Optionally clean up any MyST syntax.
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
.