Cluster-api: Changes to Gitbook business model that may affect this project

[pires]

This project seems to rely on Gitbook to generate and serve documentation. Recently, a new version of Gitbook (v2) dropped support for serving the resources locally which I think will at least affect how developers interact with the tool and the resources managed by it. Did anyone here look into this already?

cc @timothysc

[timothysc]

/assign @davidewatson @detiber @vincepri

[detiber]

We may want to take a path similar to kubebuilder, it looks like they switched to a tool called mdbook: https://github.com/kubernetes-sigs/kubebuilder/blob/master/docs/book/install-and-build.sh

[moshloop]

Another tool to consider is www.mkdocs.org - It has a GitBook theme and fairly decent plugin ecosystem including sequence diagrams with mermaid.

We could then combine it with gen-apidocs for k/k style API docs.

[moshloop]

/kind documentation

[dlipovetsky]

\ :laughing:

[moshloop]

mkdocs supports plugins so it should be easy to create a plugin to use the docker image you created to convert PlantUML -> PNG/SVG at book build time

[davidewatson]

Talked to @detiber, et al today and we agree that we should get off of GitBook. I am fine with most other solutions and also think there might be an advantage to copying kubebuilder because doing so simplifies onboarding.

[vincepri]

/lifecycle active