You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@camel.apache.org by David Jencks <da...@gmail.com> on 2020/03/27 01:13:38 UTC
[website] strategies for avoiding copying component adoc files
I’m still not happy about the amount of copying of source adoc files in the website build. The components adoc files are copied into docs/components with a gulp script run as part of the docs build, and the copies need to be checked in.
I know of two strategies to alleviate this, one available now:
1. (works but relies on unreleased Antora features); use an Antora plugin to gather the files from their locations in the components directory. The copies in docs/components could be removed.
2. replace what are now the “original” files in the components directory with symlinks to what are now the “copies” in docs/components. Since Antora would be using the copies that aren’t symlinks in docs/components, that would work fine. I haven’t tried it, but would expect that the code generation operations that modify the files based on extracted/generated json files ought to work on the symlink “copies”. Certainly editors ought to be able to deal with the symlinked copies.
I don’t know if (2) would actually work on windows, and have no way to find out.
Do either of these seem worth pursuing?
Thanks
David Jencks
Re: [website] strategies for avoiding copying component adoc files
Posted by Zoran Regvart <zo...@regvart.com>.
Hi David,
yeah let's not do work that we'll redo in not that distant future. And
btw, really good that you're following and contributing to Antora so
we can get our requirements in :)
zoran
On Fri, Mar 27, 2020 at 4:34 PM David Jencks <da...@gmail.com> wrote:
>
> Antora plugins might be available in master branch in 2-3 weeks but as for a release, it would be the next major version, and I doubt it will be out before 3 months or so, maybe longer. There’s also the actual plugin that does the work, which I can’t really release to npm before the plugin framework is stable.
>
> Maybe it’s best not to try to squeeze this into 3.2 :-)
>
> Thanks
> David
>
> > On Mar 27, 2020, at 2:36 AM, Zoran Regvart <zo...@regvart.com> wrote:
> >
> > Hi David,
> > I think both are valid approaches, with the second one looking more
> > like a workaround, quite similar to what we do with copying to
> > docs/components via Gulp. I think we're all used to committing
> > regenerated files when we forget to commit them initially, could be
> > that we got used to the pain :)
> >
> > Do you know the timeline for the release of Antora for the first
> > option. I'd go with that if possible, seems like that would have less
> > of an impact on 2.x and 3.0.x branches, so less work there.
> >
> > And you're right, support for symlinks on Windows could bring on more issues[1]
> >
> > zoran
> >
> > [1] https://github.com/git-for-windows/git/wiki/Symbolic-Links
> >
> > On Fri, Mar 27, 2020 at 2:13 AM David Jencks <da...@gmail.com> wrote:
> >>
> >> I’m still not happy about the amount of copying of source adoc files in the website build. The components adoc files are copied into docs/components with a gulp script run as part of the docs build, and the copies need to be checked in.
> >>
> >> I know of two strategies to alleviate this, one available now:
> >>
> >> 1. (works but relies on unreleased Antora features); use an Antora plugin to gather the files from their locations in the components directory. The copies in docs/components could be removed.
> >>
> >> 2. replace what are now the “original” files in the components directory with symlinks to what are now the “copies” in docs/components. Since Antora would be using the copies that aren’t symlinks in docs/components, that would work fine. I haven’t tried it, but would expect that the code generation operations that modify the files based on extracted/generated json files ought to work on the symlink “copies”. Certainly editors ought to be able to deal with the symlinked copies.
> >>
> >> I don’t know if (2) would actually work on windows, and have no way to find out.
> >>
> >> Do either of these seem worth pursuing?
> >>
> >> Thanks
> >> David Jencks
> >>
> >
> >
> > --
> > Zoran Regvart
>
--
Zoran Regvart
Re: [website] strategies for avoiding copying component adoc files
Posted by David Jencks <da...@gmail.com>.
Antora plugins might be available in master branch in 2-3 weeks but as for a release, it would be the next major version, and I doubt it will be out before 3 months or so, maybe longer. There’s also the actual plugin that does the work, which I can’t really release to npm before the plugin framework is stable.
Maybe it’s best not to try to squeeze this into 3.2 :-)
Thanks
David
> On Mar 27, 2020, at 2:36 AM, Zoran Regvart <zo...@regvart.com> wrote:
>
> Hi David,
> I think both are valid approaches, with the second one looking more
> like a workaround, quite similar to what we do with copying to
> docs/components via Gulp. I think we're all used to committing
> regenerated files when we forget to commit them initially, could be
> that we got used to the pain :)
>
> Do you know the timeline for the release of Antora for the first
> option. I'd go with that if possible, seems like that would have less
> of an impact on 2.x and 3.0.x branches, so less work there.
>
> And you're right, support for symlinks on Windows could bring on more issues[1]
>
> zoran
>
> [1] https://github.com/git-for-windows/git/wiki/Symbolic-Links
>
> On Fri, Mar 27, 2020 at 2:13 AM David Jencks <da...@gmail.com> wrote:
>>
>> I’m still not happy about the amount of copying of source adoc files in the website build. The components adoc files are copied into docs/components with a gulp script run as part of the docs build, and the copies need to be checked in.
>>
>> I know of two strategies to alleviate this, one available now:
>>
>> 1. (works but relies on unreleased Antora features); use an Antora plugin to gather the files from their locations in the components directory. The copies in docs/components could be removed.
>>
>> 2. replace what are now the “original” files in the components directory with symlinks to what are now the “copies” in docs/components. Since Antora would be using the copies that aren’t symlinks in docs/components, that would work fine. I haven’t tried it, but would expect that the code generation operations that modify the files based on extracted/generated json files ought to work on the symlink “copies”. Certainly editors ought to be able to deal with the symlinked copies.
>>
>> I don’t know if (2) would actually work on windows, and have no way to find out.
>>
>> Do either of these seem worth pursuing?
>>
>> Thanks
>> David Jencks
>>
>
>
> --
> Zoran Regvart
Re: [website] strategies for avoiding copying component adoc files
Posted by Zoran Regvart <zo...@regvart.com>.
Hi David,
I think both are valid approaches, with the second one looking more
like a workaround, quite similar to what we do with copying to
docs/components via Gulp. I think we're all used to committing
regenerated files when we forget to commit them initially, could be
that we got used to the pain :)
Do you know the timeline for the release of Antora for the first
option. I'd go with that if possible, seems like that would have less
of an impact on 2.x and 3.0.x branches, so less work there.
And you're right, support for symlinks on Windows could bring on more issues[1]
zoran
[1] https://github.com/git-for-windows/git/wiki/Symbolic-Links
On Fri, Mar 27, 2020 at 2:13 AM David Jencks <da...@gmail.com> wrote:
>
> I’m still not happy about the amount of copying of source adoc files in the website build. The components adoc files are copied into docs/components with a gulp script run as part of the docs build, and the copies need to be checked in.
>
> I know of two strategies to alleviate this, one available now:
>
> 1. (works but relies on unreleased Antora features); use an Antora plugin to gather the files from their locations in the components directory. The copies in docs/components could be removed.
>
> 2. replace what are now the “original” files in the components directory with symlinks to what are now the “copies” in docs/components. Since Antora would be using the copies that aren’t symlinks in docs/components, that would work fine. I haven’t tried it, but would expect that the code generation operations that modify the files based on extracted/generated json files ought to work on the symlink “copies”. Certainly editors ought to be able to deal with the symlinked copies.
>
> I don’t know if (2) would actually work on windows, and have no way to find out.
>
> Do either of these seem worth pursuing?
>
> Thanks
> David Jencks
>
--
Zoran Regvart