> On Sep 10, 2021, at 12:57 AM, Zoran Regvart <zo...@regvart.com> wrote:
>
> Hi David,
>
> On Thu, Sep 9, 2021 at 6:36 PM David Jencks <david.a.jen...@gmail.com> wrote:
>> 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>
>
> Up for debate really. My 2c on this is that we invested a lot of
> effort in build performance and if we add more processing to the build
> this goes against that. Also as any .adoc can link via xref to any
> other .adoc wouldn't we build a non-trivial subset of pages for every
> component .adoc? That would severely impact the build times. I much
> rather have a linter go over the .adoc file with the context of the
> component metadata and check for things we know cause issues (missing
> JSON files, missing attributes, broken xrefs...), and improve to add
> more checks as we find more common issues...
I certainly agree build speed is important. However, I also think that we
should make it difficult for people to edit the docs and not look at the
results: this is analogous to changing the java code and not checking whether
it compiles. The idea behind Dan’s site-manifest idea is that a site build can
produce a json file listing the files or resources in the Antora catalog and
then another site build can read that in to the catalog to resolve xrefs etc.
In the case of a component or similar project, the idea would be to build just
the single doc page for that component, but have the xrefs resolved to the main
site. Since we’d only be building one page, it should be very quick.
This is definitely not a solution available out-of-the-box now but perhaps
something to think about and aim for for the future. Among other things we’d
have to make the UI bundle accessible and the main site site-manifest
accessible.
If we can get this to work then the question opens of whether validating the
.adoc files is better done in javascript as part of the (1-page, here) site
build or in a maven plugin.
David Jencks
