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 2021/10/05 06:26:24 UTC
[Website] Move camel-karaf and camel-spring-boot content into
"components" component?
IIUC the camel-karaf and camel-spring-boot subprojects are always released in sync with main camel.
On the websites, for these subprojects, there is a little bit of general information, and some tables listing the parts of the “components” that are supported in the subproject (components, dataformats, etc). The table rows link to the docs in the “components” component, which is against the meaning of an Antora component.
I wonder if it would make sense to include this subproject information in the “components” component. I’m thinking the nav might look like
Components
Dataformats
Languages
Other
EIPS
Camel-Spring-Boot
- components
- dataformats
- languages
- other
Camel-Karaf
- components
- dataformats
- languages
- other
I think this would be pretty easy to do, and it would definitely leave everything in the repo it is currently in. Does this idea seem interesting enough that I should prepare a PR/prototype?
David Jencks
Re: [Website] Move camel-karaf and camel-spring-boot content into
"components" component?
Posted by David Jencks <da...@gmail.com>.
Let’s try again…
What I’m proposing here does not move any sources to different repos or change how e.g. the spring-boot tables of components etc are generated. I think it’s completely appropriate for the code generation etc for camel-spring-boot and camel-karat to be in separate repositories, and how tables are generated is an independent issue.
I think that normally in an Antora component you want to present a cohesive set of information. I think that means that the vast majority of the links in the component will be to other pages in the same component. Otherwise, when you click a link, suddenly you’ll be in a completely different component environment, which I regard as extremely surprising.
Right now, almost everything in camel-spring-boot and camel-karaf is a link to a different component, the “components” component. In particular, I find this disorienting. I click a link and think, “what happened, where did camel-spring-boot go?? I’m looking at the main activemq page!! How do I get back to spring-boot info??”
I’m proposing that we consider presenting the camel-spring-boot and camel-karaf info as part of the “components” component, having sections for each in the components nav, under the existing stuff. I also think it’s a good idea to have items in the nav for components, dataformats, etc, so the presentation is parallel to the main components nav. These could either be simply links to the relevant tables, or expand to lists like the existing nav does (this would add another layer of nesting to the nav).
Hopefully this explanation will make my text mockup of the proposed nav more comprehensible.
Some subsidiary points:
IIUC spring-boot and karaf are “extras” that come with most but not all components/dataformats etc. I haven’t thought about how this might be done, but I think it would be nice to have something like badges at the top of each component page, “spring-boot yes”, “karaf yes”. Possibly this would be appropriate for other subprojects: I’m pretty sure it would be for camel-quarkus.
I’m not all that familiar with the other sub-projects, but I think they don’t have a 1-1 relationship with main camel components. For instance my understanding is that camel-quarkus bundles one or more components into a quarkus “thing”, and the camel-quarkus page explains this bundling. If there are any other subprojects that do have a necessary 1-1 relation to main camel components, they could have their documentation folded into the main components docs in the same way.
David Jencks
> On Oct 5, 2021, at 12:20 AM, Claus Ibsen <cl...@gmail.com> wrote:
>
> Hi David
>
> Can you explain in more detail what you mean by moving "information"
> to "components".
>
> If you refer to that there is a .adoc file that is generating a big
> table such as
> https://raw.githubusercontent.com/apache/camel-spring-boot/main/docs/modules/ROOT/pages/list.adoc
>
> Then that is generated via a maven plugin, that scans the source code
> and builds up that table.
>
> The list is then used on the website to list all the supported Spring
> Boot starters.
> https://camel.apache.org/camel-spring-boot/latest/list.html
>
> That list used the xref links like we do in other places for Camel
> components, languages, data formats, etc.
> What is it that goes against the meaning of an Antora component?
>
> IMHO the system we have with the maven plugin that generates that
> single file works well.
> And the docs are in the src/main/docs folder for each of those spring
> boot starters.
> So we can maintain it where it belongs.
>
>
>
> On Tue, Oct 5, 2021 at 8:26 AM David Jencks <da...@gmail.com> wrote:
>>
>> IIUC the camel-karaf and camel-spring-boot subprojects are always released in sync with main camel.
>>
>> On the websites, for these subprojects, there is a little bit of general information, and some tables listing the parts of the “components” that are supported in the subproject (components, dataformats, etc). The table rows link to the docs in the “components” component, which is against the meaning of an Antora component.
>>
>> I wonder if it would make sense to include this subproject information in the “components” component. I’m thinking the nav might look like
>>
>> Components
>> Dataformats
>> Languages
>> Other
>> EIPS
>>
>> Camel-Spring-Boot
>> - components
>> - dataformats
>> - languages
>> - other
>>
>> Camel-Karaf
>> - components
>> - dataformats
>> - languages
>> - other
>>
>> I think this would be pretty easy to do, and it would definitely leave everything in the repo it is currently in. Does this idea seem interesting enough that I should prepare a PR/prototype?
>>
>> David Jencks
>
>
>
> --
> Claus Ibsen
> -----------------
> http://davsclaus.com @davsclaus
> Camel in Action 2: https://www.manning.com/ibsen2
Re: [Website] Move camel-karaf and camel-spring-boot content into
"components" component?
Posted by David Jencks <da...@gmail.com>.
This is another issue, but I’m thinking about it :-)
David Jencks
> On Oct 5, 2021, at 12:26 AM, Claus Ibsen <cl...@gmail.com> wrote:
>
> Hi
>
> Btw on another note, then we have for camel-spring-boot and
> camel-karaf a "catalog" which holds JSon files with information for
> every JAR they support.
>
> https://github.com/apache/camel-spring-boot/tree/main/catalog/camel-catalog-provider-springboot
>
> The same for karaf at
> https://github.com/apache/camel-karaf/tree/main/catalog/camel-catalog-provider-karaf
>
> If this is the case, then I think what you did for the core camel
> project was to use this to generate the list of components there.
> If this can be done the same way, then we can do it similarly, and we
> can then remove that maven plugin that generates that list.adoc file.
>
> On Tue, Oct 5, 2021 at 9:20 AM Claus Ibsen <cl...@gmail.com> wrote:
>>
>> Hi David
>>
>> Can you explain in more detail what you mean by moving "information"
>> to "components".
>>
>> If you refer to that there is a .adoc file that is generating a big
>> table such as
>> https://raw.githubusercontent.com/apache/camel-spring-boot/main/docs/modules/ROOT/pages/list.adoc
>>
>> Then that is generated via a maven plugin, that scans the source code
>> and builds up that table.
>>
>> The list is then used on the website to list all the supported Spring
>> Boot starters.
>> https://camel.apache.org/camel-spring-boot/latest/list.html
>>
>> That list used the xref links like we do in other places for Camel
>> components, languages, data formats, etc.
>> What is it that goes against the meaning of an Antora component?
>>
>> IMHO the system we have with the maven plugin that generates that
>> single file works well.
>> And the docs are in the src/main/docs folder for each of those spring
>> boot starters.
>> So we can maintain it where it belongs.
>>
>>
>>
>> On Tue, Oct 5, 2021 at 8:26 AM David Jencks <da...@gmail.com> wrote:
>>>
>>> IIUC the camel-karaf and camel-spring-boot subprojects are always released in sync with main camel.
>>>
>>> On the websites, for these subprojects, there is a little bit of general information, and some tables listing the parts of the “components” that are supported in the subproject (components, dataformats, etc). The table rows link to the docs in the “components” component, which is against the meaning of an Antora component.
>>>
>>> I wonder if it would make sense to include this subproject information in the “components” component. I’m thinking the nav might look like
>>>
>>> Components
>>> Dataformats
>>> Languages
>>> Other
>>> EIPS
>>>
>>> Camel-Spring-Boot
>>> - components
>>> - dataformats
>>> - languages
>>> - other
>>>
>>> Camel-Karaf
>>> - components
>>> - dataformats
>>> - languages
>>> - other
>>>
>>> I think this would be pretty easy to do, and it would definitely leave everything in the repo it is currently in. Does this idea seem interesting enough that I should prepare a PR/prototype?
>>>
>>> David Jencks
>>
>>
>>
>> --
>> Claus Ibsen
>> -----------------
>> http://davsclaus.com @davsclaus
>> Camel in Action 2: https://www.manning.com/ibsen2
>
>
>
> --
> Claus Ibsen
> -----------------
> http://davsclaus.com @davsclaus
> Camel in Action 2: https://www.manning.com/ibsen2
Re: [Website] Move camel-karaf and camel-spring-boot content into
"components" component?
Posted by Claus Ibsen <cl...@gmail.com>.
Hi
Btw on another note, then we have for camel-spring-boot and
camel-karaf a "catalog" which holds JSon files with information for
every JAR they support.
https://github.com/apache/camel-spring-boot/tree/main/catalog/camel-catalog-provider-springboot
The same for karaf at
https://github.com/apache/camel-karaf/tree/main/catalog/camel-catalog-provider-karaf
If this is the case, then I think what you did for the core camel
project was to use this to generate the list of components there.
If this can be done the same way, then we can do it similarly, and we
can then remove that maven plugin that generates that list.adoc file.
On Tue, Oct 5, 2021 at 9:20 AM Claus Ibsen <cl...@gmail.com> wrote:
>
> Hi David
>
> Can you explain in more detail what you mean by moving "information"
> to "components".
>
> If you refer to that there is a .adoc file that is generating a big
> table such as
> https://raw.githubusercontent.com/apache/camel-spring-boot/main/docs/modules/ROOT/pages/list.adoc
>
> Then that is generated via a maven plugin, that scans the source code
> and builds up that table.
>
> The list is then used on the website to list all the supported Spring
> Boot starters.
> https://camel.apache.org/camel-spring-boot/latest/list.html
>
> That list used the xref links like we do in other places for Camel
> components, languages, data formats, etc.
> What is it that goes against the meaning of an Antora component?
>
> IMHO the system we have with the maven plugin that generates that
> single file works well.
> And the docs are in the src/main/docs folder for each of those spring
> boot starters.
> So we can maintain it where it belongs.
>
>
>
> On Tue, Oct 5, 2021 at 8:26 AM David Jencks <da...@gmail.com> wrote:
> >
> > IIUC the camel-karaf and camel-spring-boot subprojects are always released in sync with main camel.
> >
> > On the websites, for these subprojects, there is a little bit of general information, and some tables listing the parts of the “components” that are supported in the subproject (components, dataformats, etc). The table rows link to the docs in the “components” component, which is against the meaning of an Antora component.
> >
> > I wonder if it would make sense to include this subproject information in the “components” component. I’m thinking the nav might look like
> >
> > Components
> > Dataformats
> > Languages
> > Other
> > EIPS
> >
> > Camel-Spring-Boot
> > - components
> > - dataformats
> > - languages
> > - other
> >
> > Camel-Karaf
> > - components
> > - dataformats
> > - languages
> > - other
> >
> > I think this would be pretty easy to do, and it would definitely leave everything in the repo it is currently in. Does this idea seem interesting enough that I should prepare a PR/prototype?
> >
> > David Jencks
>
>
>
> --
> Claus Ibsen
> -----------------
> http://davsclaus.com @davsclaus
> Camel in Action 2: https://www.manning.com/ibsen2
--
Claus Ibsen
-----------------
http://davsclaus.com @davsclaus
Camel in Action 2: https://www.manning.com/ibsen2
Re: [Website] Move camel-karaf and camel-spring-boot content into
"components" component?
Posted by Claus Ibsen <cl...@gmail.com>.
Hi David
Can you explain in more detail what you mean by moving "information"
to "components".
If you refer to that there is a .adoc file that is generating a big
table such as
https://raw.githubusercontent.com/apache/camel-spring-boot/main/docs/modules/ROOT/pages/list.adoc
Then that is generated via a maven plugin, that scans the source code
and builds up that table.
The list is then used on the website to list all the supported Spring
Boot starters.
https://camel.apache.org/camel-spring-boot/latest/list.html
That list used the xref links like we do in other places for Camel
components, languages, data formats, etc.
What is it that goes against the meaning of an Antora component?
IMHO the system we have with the maven plugin that generates that
single file works well.
And the docs are in the src/main/docs folder for each of those spring
boot starters.
So we can maintain it where it belongs.
On Tue, Oct 5, 2021 at 8:26 AM David Jencks <da...@gmail.com> wrote:
>
> IIUC the camel-karaf and camel-spring-boot subprojects are always released in sync with main camel.
>
> On the websites, for these subprojects, there is a little bit of general information, and some tables listing the parts of the “components” that are supported in the subproject (components, dataformats, etc). The table rows link to the docs in the “components” component, which is against the meaning of an Antora component.
>
> I wonder if it would make sense to include this subproject information in the “components” component. I’m thinking the nav might look like
>
> Components
> Dataformats
> Languages
> Other
> EIPS
>
> Camel-Spring-Boot
> - components
> - dataformats
> - languages
> - other
>
> Camel-Karaf
> - components
> - dataformats
> - languages
> - other
>
> I think this would be pretty easy to do, and it would definitely leave everything in the repo it is currently in. Does this idea seem interesting enough that I should prepare a PR/prototype?
>
> David Jencks
--
Claus Ibsen
-----------------
http://davsclaus.com @davsclaus
Camel in Action 2: https://www.manning.com/ibsen2