Containerize the docs build/test system

[theletterf]

Building and testing docs locally might be a source of unwanted friction when it comes to contributing docs. While our CI does a great job at dealing with those aspects on GitHub, building and fixing the docs locally requires a Node environment that may or may not always be simple to provision on a machine.

My suggestion here is to containerize the build/test environment so that one would only have to run a shell script (or a BAT) file to have the local container runtime spin up a build system. We do this at Splunk for our public docs due to how tricky it is to set up and configure a functional Python environment: https://github.com/splunk/public-o11y-docs/blob/main/start.sh

For our docs, which rely on npm and Hugo, this might not be as critical, though I do have to use nvm use 18 from time to time. Not all contributors to our docs might have the technical skills to manage Node environments on a machine. The use of a container would also allow us to install, pin, and generally protect binaries and better control the build UX.

By maintaining a freedom principle, we could offer — and maintain — all three ways of building and testing docs locally, containerized, cloud IDE (Gitpod), and non-containerized.

[theletterf]

@open-telemetry/docs-maintainers Any thought on this?

[hughesjj]

I think this is a great idea and we should do it

[svrnm]

As long as the "non-containerized" version works I am totally fine with it.

[chalin]

Building and testing docs locally might be a source of unwanted friction ...

(Emphasis mine in the quote above.)

Have we had any complaints?

I'd vote against this for now, given that are main dependency is on Node. IMHO, we have enough on our plate w/o having to bring in another environment setup/config to document and maintain. My 2 cents.

(Once/if the code-snippet tools are brought in we might revisit this. Then again, we might be able to use the new JS versions that are being vetted.)

[svrnm]

I agree on the "we can/should do this, but not now" part

[EzzioMoreira]

@theletterf great idea 👍, I think we should change bash to makefile, the user execute make server-run command to run website locally.

Here is an example of the Kubernetes project.
https://github.com/kubernetes/website/blob/7093f2c54d6954762d1df83e40859f40bf1f2c64/Makefile#L103

[chalin]

@EzzioMoreira - are you having issues building and/or serving? If so, what are the specific issues that you are facing? I want to avoid unnecessary tooling bloat (via alternative ways to build) and bike shedding, if there is no clear problem being addressed.

Re. Make: eliminating Make from our tooling equation has been on my list for a while (and I'm almost there). I like our NPM-based script i/f for tooling. It isn't perfect (but then again, no toolset is), but it is relatively clean and simple (even if we need to fall into support bash scripts).