search

coreos / fedora-coreos-docs

Documentation for Fedora CoreOS
https://docs.fedoraproject.org/en-US/fedora-coreos/
Other
51 stars 123 forks source link

Providing alternative examples #553

Open Okeanos opened 1 year ago

Okeanos commented 1 year ago

There is an open PR (#171) and a couple of merged PRs (#543, #213) that deal with alternative examples / example environment different from the default Linux one.

Additionally, tooling for FCOS is available on Linux, macOS, and Windows each with their own idiosyncrasies and caveats. I am wondering whether it makes sense to … streamline the documentation here a little and use e.g. asciidoctor-tabs to provide "standard" means to offer examples for different platforms & environments?

travier commented 1 year ago

That looks like a good idea. However the Fedora CoreOS documentation is built and hosted on Fedora Infrastructure and I don't know if we have this extension available there.

Okeanos commented 1 year ago

I think it should be technically possible to include the extension directly via the existing playbook by adding an extensions list with the value '@asciidoctor/tabs'`. That assumes the actual build process has access to the internet (which it should because you source the UI from gitlab.com).

However, the "fun" part is then having to dynamically rewrite and include so called supplemental files. I can totally see why you wouldn't want to do that and instead rely on a neatly packaged and complete base UI package styled in the official Fedora design. Including the extension "out of turn" effectively makes the CoreOS documentation brittle and unnecessarily hard to maintain.

I suppose this would then be a base line issue (+ PR) over at Fedora Docs Website in the Fedora Doc UI repository? Once official support for this exists only the extension would have to be included as "we use this"-declaration without having to worry about breaking styling.

travier commented 1 year ago

Yes, if you can bring that up with the docs team there that would be great as they likely have more info about the build process and how this is set up overall.

Okeanos commented 1 year ago

Just as a heads-up here. I believe this should best be tackled after Fedora Docs' site CSS breaks many AsciiDoctor features has been resolved.

travier commented 1 year ago

Dusty asked about this at https://gitlab.com/fedora/docs/docs-website/ui-bundle/-/issues/12

travier commented 7 months ago

This has been deployed in the Fedora infra, so we should be able to use it now: https://gitlab.com/fedora/docs/docs-website/ui-bundle/-/issues/12

Okeanos commented 7 months ago

Thanks for the update!