search

blue-build / modules

BlueBuild standard modules used for building your Atomic Images
Apache License 2.0
23 stars 25 forks source link

refactor: start using module.yml for documentation #116

Closed xynydev closed 5 months ago

xynydev commented 5 months ago

We now have these cool module reference pages generated from this repo. Check it out: https://blue-build.org/reference/modules/akmods/ (per https://github.com/blue-build/website/issues/3 and https://github.com/blue-build/website/pull/26)

Currently the only inputs are the module.ymls in this branch and the README's aren't used at all. I just transformed the content to the module.yml while doing some small improvements.

I'm now thinking that maybe a hybrid approach could work better, with the description: from module.yml being refactored away, instead using the README for the description. This would allow both for programmatic reading of the module metadata, and a slightly more comfortable experience for the module documentation writer. What do y'all think?

fiftydinar commented 5 months ago

I'm in for this change, I like it

fiftydinar commented 5 months ago

!WARNING cards are not shown though for some reason.

In akmods module, I would put everything under 1 !WARNING, with Shift + Enter, instead of using 3 of them like I did before.

If !WARNING does not work, It's alright to use !CAUTION instead.

Everything else looks pretty good

xynydev commented 5 months ago

Do you think module.yml+README is better than just module.yml?

xynydev commented 5 months ago

!WARNING cards are not shown though for some reason.

Starlight (which we use for the docs) has different syntax and I'll be fixing that in this PR later.

fiftydinar commented 5 months ago

Do you think module.yml+README is better than just module.yml?

I think that module.yml only approach is better, even if README could be more convenient for editing docs. It makes everything in 1 place.

I would maybe put module.yml to be separate, in website repo maybe, so we could separate module content only & module website documentation.

xynydev commented 5 months ago

I think that module.yml only approach is better, even if README could be more convenient for editing docs. It makes everything in 1 place.

Alright. I'm not sure if I agree but I'll wait to hear what others think.

I would maybe put module.yml to be separate, in website repo maybe, so we could separate module content only & module website documentation.

That is the exact opposite of what I'm trying to achieve with this. Documentation should be in the same place as source code, so that it can be updated at the same time as source code. Besides, the website probably might not be the only repo to use these files down the line.

fiftydinar commented 5 months ago

Hmm, I see.

module.yml + README does sound better when you mentioned your goal below. I suggested module.yml only at 1st for aesthetic purposes only, which I know you care about.

It's better to avoid editing files in more separate places, like we did before in Ublue (module logic in bling repo, module docs in website repo).

So I vote for module.yml + README