How to build the Plone documentation locally?

Hi,

while reading the excellent Plone documentation over at https://docs.plone.org I found some formatting issues, which I'd like to fix myself.

Before making a PullRequest, I'd like to build the docs locally.

For e.g. the Zope documentation I just have to execute bin/make-docs (which is a wrapper around a call to a makefile).

For the Plone documentation I cannot find any info on how to generate the docs locally.

I have to admit I am not very adept with the whole process of generating documentation, so maybe I overlook something.

Can anybody give me a hint on how to build the documentation locally?

Thank you very much.

Some of the docs under docs.plone.org get pulled in from other repos.

If it is a training, see https://training.plone.org/5/index.html, specifically https://training.plone.org/5/mastering-plone/about_mastering.html#building-the-documentation-locally

For building the entire docs locally, the README used to have something, but it appears to have vanished. See https://github.com/plone/documentation/pull/920/files

@svx @polyester @loechel what happened here? I looked on both the 5.1 and 5.2 branches for the missing instructions.

1 Like

Building the docs locally is not super-friendly, to put it mildly, since it pulls in a lot of dependencies.

You can, however, and https://github.com/plone/papyrus/blob/5.2/docs/install.rst is how to do it.
(you can skip the texlive-packages if all you want to create is HTML)

Reading the installation instruction, now I am a little bit scared, but not enough to not try it.

Thank you very much @polyester

I was able to build it locally!

There is one question left. How do I build the checked out local and updated Plone docs repo, as I think that the make process pulls the docs from the official Github repo, where my changes are not yet published?

As a quickfix I copy/pasted my local changes into the checkouts directory (:nerd_face:) -but there must be a better way! :slight_smile:

P.S.:
With these many dependencies this setup looks like the first real world use case I encounter for possibly using a Docker image?

1 Like

@jugmac00, normally what I do:

  • create a new branch on plone/documentation, do your changes there
  • once happy, checked against the documentation style guide and the rst style guide and it builds locally
  • then create a pull request from your branch

as for the Docker question; there is work on that going on for future versions. Long story short: for the current (imperfect) Papyrus setup, we are not likely to change the process. Limited resources and stuff...

1 Like

Thank you once again!

During lunch break I came up with a solution. I do not checkout plone/documentation manually, but via papyrus and apply the changes directly in the checkouts/documentation subfolder on a new branch, and then create the pr from that branch.

That seems to work.

Is this the same procedure like yours?

Anyway, thank you for your time.

PR is already merged.

1 Like