Containerize the docs build/test system #3810
theletterf
started this conversation in
Tooling & Infrastructure
Replies: 2 comments 3 replies
-
@open-telemetry/docs-maintainers Any thought on this? |
Beta Was this translation helpful? Give feedback.
2 replies
-
(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.) |
Beta Was this translation helpful? Give feedback.
1 reply
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
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.
Beta Was this translation helpful? Give feedback.
All reactions