Simplify the documentation building

LecrisUT commented 6 months ago

Moved the docs/Makefile to inside conf.py to run automatically (reference: https://breathe.readthedocs.io/en/latest/readthedocs.html)
~~Added more sphinx builders~~ Moved to individual PRs. See #2487

I've added these as GitHub Actions instead of pre-commits because:

It usually requires the installation of tmt itself
It can be a bit heavy for pre-commits

happz commented 6 months ago

Another one considered was spelling, but that one would require to maintain a dictionary of technical words used. Can add it as well if you think it's useful.

I think it would be a nice addition. Or a similar tool. Having a spellchecker in play would be nice, to avoid typos and improve consistency (saying "html" at one place and "HTML" elsewhere..., or my classic "tmt" vs "Tmt" vs "TMT" :)

It is a bit annoying because it doesn't pick up on apostrophes (e.g. we've)

Ok, I'd vote to get rid of the apostrophes and be verbose, i.e. "we have" in the docs...

or dashes (e.g. omni-present).

That we could improve by adding words to a list of allowed ones.

If there is an alternative to that would love to hear.

I'm not sure whether there are alternatives. Maybe it's also possible to use some integration with tools capable of checking not just spelling but also semantics ("it's" vs "its") and punctuation, like Grammarly (or ChatGPT :) But starting with at least a spellchecker would improve things.

Edit: I'm playing a bit with the spelling builder, putting together a list of words to allow, and it doesn't look as bad as I expected. 80/20 in action, I guess, plus some really valid issues found, like "url" vs "URL", "yaml" where "YAML" should be, and some actual technical stuff like "httpd" or "beakerlib". I'll try to make a PR out of it, this looks like fun :)

LecrisUT commented 6 months ago

Ok, I've switched it to the combined Makefile+native sphinx format, and opened issues to track the rest. I've also factored out the other parts to dedicated PRs

happz commented 6 months ago

/packit build

LecrisUT commented 3 months ago

@happz @lukaszachy This should also go into a milestone. Do we have anything more to discuss for this one?

happz commented 3 months ago

@happz @lukaszachy This should also go into a milestone. Do we have anything more to discuss for this one?

I’ll refresh my memory by re-reading comments, but we can definitely have a milestone for this.

happz commented 1 month ago

Works for me. Needs a rebase, but my local make docs produced the expected stuff (I use these docs often, to both read about tmt and check how the docs are rendered).