> On Sep 8, 2021, at 11:22 AM, Zoran Regvart <zo...@regvart.com> wrote: > > Hi David & Cameleers, > > On Wed, Sep 8, 2021 at 4:48 PM David Jencks <david.a.jen...@gmail.com > <mailto:david.a.jen...@gmail.com>> wrote: >> >>> <snip> >>>>>> - If nothing else is using the model building in UpdateReadmeMojo it can >>>>>> probably be simplified further. >>>>> >>>>> From what I understand we only need the JSON files generated now, >>>>> perhaps the we don't need the UpdateReadmeMojo at all any more? >>>> >>>> Perhaps. It still generates the doc header. If Allow asciidoctor >>>> extensions when processing nav files and headers >>>> <https://gitlab.com/antora/antora/-/issues/592> were implemented, the >>>> header generation could be done by the jsonpath extension, but I’m not >>>> sure how much of an improvement that would be. In any case, >>>> UpdateReadmeMojo is now more of a sanity checker than content generator >>>> :-). >>> >>> I kinda think that we should have a prescribed attributes that any >>> document needs to be published and if there are attributes missing or >>> values don't make sense then that needs to be corrected. I saw this >>> work as a good way to reduce the amount of regen commits and moving >>> this to a responsibility of the author. >>> >>> Perhaps we can change the role of the UpdateReadmeMojo (and rename >>> it), to be a linter for the documentation? Any thoughts >>> Claus/Andrea/others? >> >> If we agree it should be only a checker, the functionality could also be >> implemented as an Antora pipeline extension. This would fail the site build >> rather than doing something during the java build. I don’t know whether or >> not this would be a good idea, but it’s a possibility :-) > > I think the website build is far removed from the other projects, so > by the time folk see the issue the context has already been forgotten. > Especially for new contributors, contributing a new component and doc > improvements, they might find it confusing that everything was built > okay, but the page on the website, or even the website build is > broken.
Currently indeed that is a problem, but on the other hand I think that we don’t want people changing the documentation without looking at the result in the site, at least the result for the page(s) they changed. I wonder if we could have, as part of the maven build of a component, perhaps in a profile, Antora build just that component's doc page. It might be possible to make this visible as part of the whole Antora site using the site-manifest idea Dan’s been working on. I turned this into a (non-standard, so far) pipeline extension: antora-site-manifest <https://gitlab.com/djencks/antora-site-manifest> David Jencks
