Good Morning,
Currently SIGs doc leverages mkdocs built via a container. I was wondering if the CentOS infra team has an idea of how much work it would be to migrate to other format keeping the container as a tooling/building mechanism. In other words, if a SIG is interested in building its documentation using something else than mkdocs but still built via a container, would it be possible for the infra team to adjust the pipeline and if so how much work would that represent?
Thanks in advance for your thoughts :)
Metadata Update from @arrfab: - Issue tagged with: blocked, feature-request, investigation
Well, the official CentOS Docs SIG even discussed on the specific day after Fosdem (there was a Docs SIG day) about consolidating everything to mkdocs format, and there is even a goal they had to convert existing https://docs.centos.org to that same mkdocs format, used actually for SIGs.
CentOS Docs SIG
I'll let @shaunm comment on your request
@shaunm ?
My understanding of the build process it that each individual doc is built separately and dropped into place, and then another separate process creates the index page. If that's correct, it seems like it ought to be possible to have different docs built with different tools. Here are some issues I anticipate:
It will be hard to match the look and feel. Right now, the index page doesn't look like the pages of the docs. That's not the worst thing, but it would be nice to be consistent. Aside from the look, there's the general layout. For example, I know on every SIG doc, there's a link to the source in the top-right corner. That's nice to have consistent.
Having a single format and build tool makes it easier for people to contribute across different documents. That's especially nice for SIGs that have a lot of membership overlap. I'm guessing this request is for Automotive, which I guess has a pretty specialized membership.
Every build tool we introduce brings an added maintenance burden to infra. I know in principle a containerized build tool should just work every time. But also in practice, every time I'm at a new machine I have to figure out how to get the containerized Jekyll working again for the main site. Maybe the tool you're looking at has a more robust container. The infra team would need to see how much this increases their workload.
Summary: I'm not entirely opposed, if there's a strong case for something (e.g. reusing existing content pools that are already in another format). It's just something we should carefully consider, and not just open the floodgates for everyone's favorite docs tool.
Log in to comment on this ticket.