✨ Update docs/Makefile

[oscr]

What this PR does / why we need it:

I noticed that the docs/Makefile diagrams target uses an old PlantUML container from k8s.gcr.io. I took some inspiration from OpenStack provider and updated the Makefile in the following way.

• Add a help target.
• Add diagram build container target.
• Update diagram build target to use local image.
• Update Dockerfile usage instructions.

Finally I also regenerated the proposal diagrams since they where generated with an older version of PlantUML.

Makefile help output:

make 

Usage:
  make <target>

build
  diagrams         Make PlantUML diagrams
  plantuml-builder  Make diagram build container

general
  help             Display this help

[k8s-ci-robot]

@oscr: This issue is currently awaiting triage.

If CAPI contributors determines this is a relevant issue, they will accept it by applying the triage/accepted label and provide further guidance.

The triage/accepted label can be added by org members by writing /triage accepted in a comment.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[oscr]

/test pull-cluster-api-verify-main

[killianmuldoon]

I think we should be careful with the differences between the new and old images - some of them appear to be incorrectly formatted so we might need to update the plantuml files so that the resulting images are closer to the originals.

Would it be possible to do this incrementally? I understand there might be a large amount of work to update the images so the newer version of plantuml produces something close to the original versions. If it's possible we could create an umbrella task to update these images one-by-one (or batch by batch)

[oscr]

What would you say about removing the updates to proposals and change the "make diagrams" just builds the CAPI book? The proposals don't need to be updated so we can just let them be. Then in a separate pr we can either update the diagrams target or add a separate target for proposals diagrams together with fixes for them. Sounds ok @killianmuldoon?

[killianmuldoon]

Could we maybe add two targets - make diagrams-book and make diagrams-proposals? We could then aggregate them under make-diagrams. I don't think we run this command as part of any wider workflow so it would be fine to exclude the proposals for now.

We would need a solution to the broken proposal images sooner rather than later though as it would impact anyone trying to create new images for a proposal.

[killianmuldoon]

I must have missed the updates on #7017 - it looks like there's a few issues there as well. Have you made any progress on figuring out why the layering / opacity is changing? I think that's the fundamental problem, everybody else seemed happy with the colors on that PR 😆

[killianmuldoon]

Thanks for making the updates!

/lgtm

[vincepri]

/approve

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: vincepri

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [vincepri]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment