Polish docs Makefile

[happz]

• add comments to variables, targets and their groups,
• reduce duplication with custom functions (mostly around plugin docs),
• slightly increased padding for target name when rendering help, to keep things aligned even for the longest target.

Pull Request Checklist

• implement the feature

[LecrisUT]

Btw, doesn't the makefile not account for the fmf file dependencies right now? There are even more subtle dependencies on git branch and such when we were looking at linkcheck (is there really no sphinx role or such to point to git repo files?).

[happz]

Btw, doesn't the makefile not account for the fmf file dependencies right now?

Nope, not yet, although I could add collection of spec/story fmf files & add them as dependencies. That shouldn't be hard, and it's quite a visible dependency.

There are even more subtle dependencies on git branch and such when we were looking at linkcheck (is there really no sphinx role or such to point to git repo files?).

True, but I chose to ignore those :) If we start adding these, we should probably fix also the top-level Makefile as it builds bits from the sources, a branch change would affect the outcome for sure.

[thrix]

LGTM

[psss]

@happz, could you please rebase on the latest main?