Re: [Website] camel-spring-boot docs

[David Jencks]

I’ve implemented (3) and (4) on all active camel-spring-boot branches, I think 
they are pretty much ready to merge.  Discussion is on another thread, 
"[Website] Spring-boot errors or mistakes”

I don’t think I have anything else to say on this thread.

Thanks
David Jencks

> On Oct 7, 2021, at 3:17 PM, David Jencks  wrote:
> 
> (1) and (2) are now completely implemented on all active camel-spring-boot 
> branches.  I’m working on (3).
> 
> David Jencks
> 
>> On Oct 2, 2021, at 6:02 PM, David Jencks > > wrote:
>> 
>> I went ahead and implemented the first two of these in main “latest” 
>> branches. Other than removing 324 unreferenced and inaccessible pages, I 
>> don’t see any changes (There’s one slight change to the single reference to 
>> one of the removed pages: (diff is new to old)
>> 
>> < Also add any component starters 
>> your Spring Boot application requires. For example this adds the > href="../../components/3.11.x/activemq-component.html#_spring_boot_auto_configuration"
>>  class="page">auto-configuration starter for the > href="../../components/3.11.x/activemq-component.html" class="page">ActiveMQ 
>> component.
>> ---
>> > And any component starters your 
>> > Spring Boot application requires. For example this adds the > > href="activemq-starter.html" class="page">starter for the > > href="../../components/3.
>> 
>> (instead of linking to an otherwise inaccessible page, it links to the 
>> section where that content is included in the activemq component page.)
>> 
>> PRs:
>> https://github.com/apache/camel-website/pull/641 
>>  (incomplete, pending 
>> merging other two or 8, see below)
>> https://github.com/apache/camel-spring-boot/pull/374 
>>  (moves generated 
>> content to "partials" in a separate directory tree)
>> https://github.com/apache/camel/pull/6200 
>>  (changes includes of this 
>> content)
>> 
>> Since this removes a lot of pages, I’d like to apply this idea to all the 
>> active camel-spring-boot branches (latest, 3.12.x, 3.11.x, 3.7.x).
>> 
>> I was hoping to replace copying the AsciiDoc files with symlinks, but I’d 
>> forgotten how cantankerous Ant is and couldn’t find a way to use it’s 
>> symlink task, and I’m hesitant to bring node/gulp in to the project just to 
>> make some symlinks.
>> 
>> David Jencks
>> 
>>> On Oct 2, 2021, at 10:17 AM, David Jencks >> > wrote:
>>> 
>>> I always forget that for Antora terms often have a specific meaning that 
>>> isn’t that common or obvious :-)
>>> 
 On Oct 2, 2021, at 12:45 AM, Claus Ibsen >>> > wrote:
 
 On Fri, Oct 1, 2021 at 11:30 PM David Jencks >>> > wrote:
> 
> I looked at camel-spring-boot a little bit and have several questions and 
> suggestions… if there’s agreement I’ll open some issues and work on them.
> 
> 1. The AsciiDoc pages are only included in the main 
> component/dataformat/… pages, and not accessible through navigation 
> standalone.  I think they should be partials, not standalone pages.
> 
 
 You can possible not do this as the ascii doc is generated with
 information from spring boot itself, there are some camel spring boot
 started components that have spring boot auto configuration,
 that information are not in the camel-catalog, but are stored in
 spring boot style (inside the JAR in META-INF there is a spring boot
 json file).
 
 
>>> 
>>> This just involves moving the target location of the generated pages to 
>>> modules/ROOT/partials from modules/ROOT/pages, and in main camel components 
>>> changing the include::….page$... to include::….partial$…
>>> This would not be a good idea if there was a firm plan to, at some point, 
>>> also have this information on standalone pages, or convert the current 
>>> include:: to a link to a standalone page.  Otherwise, it’s simple and 
>>> shouldn’t disrupt anything. The generated spring boot docs would still be 
>>> in the camel-spring-boot repo.
>>> 
 
> 2. The individual generated pages are tied 1-1 with the ‘components’ 
> component.  I think, even though they are (at least currently) in a 
> different repo having them in the ‘components’ component as part of a 
> distributed component makes more sense than having them in a different 
> component.
> 
 
 Not sure what you mean?
>>> 
>>> We’d need 2 directories in camel-spring-boot docs, say
>>> 
>>> components/modules/spring-boot/partials  where all the individual generated 
>>> pages go, with a components/antora.yml specifying name: components and 
>>> version: 
>>> 
>>> and
>>> 
>>> spring-boot/modules/ROOT/pages where the 3 or 4 other non-generated pages 
>>> go with the current antora.yml.
>>> 
>>> I think this 

Re: [Website] camel-spring-boot docs

[David Jencks]

(1) and (2) are now completely implemented on all active camel-spring-boot 
branches.  I’m working on (3).

David Jencks

> On Oct 2, 2021, at 6:02 PM, David Jencks  wrote:
> 
> I went ahead and implemented the first two of these in main “latest” 
> branches. Other than removing 324 unreferenced and inaccessible pages, I 
> don’t see any changes (There’s one slight change to the single reference to 
> one of the removed pages: (diff is new to old)
> 
> < Also add any component starters 
> your Spring Boot application requires. For example this adds the  href="../../components/3.11.x/activemq-component.html#_spring_boot_auto_configuration"
>  class="page">auto-configuration starter for the  href="../../components/3.11.x/activemq-component.html" class="page">ActiveMQ 
> component.
> ---
> > And any component starters your 
> > Spring Boot application requires. For example this adds the  > href="activemq-starter.html" class="page">starter for the  > href="../../components/3.
> 
> (instead of linking to an otherwise inaccessible page, it links to the 
> section where that content is included in the activemq component page.)
> 
> PRs:
> https://github.com/apache/camel-website/pull/641 
>  (incomplete, pending 
> merging other two or 8, see below)
> https://github.com/apache/camel-spring-boot/pull/374 
>  (moves generated 
> content to "partials" in a separate directory tree)
> https://github.com/apache/camel/pull/6200 
>  (changes includes of this content)
> 
> Since this removes a lot of pages, I’d like to apply this idea to all the 
> active camel-spring-boot branches (latest, 3.12.x, 3.11.x, 3.7.x).
> 
> I was hoping to replace copying the AsciiDoc files with symlinks, but I’d 
> forgotten how cantankerous Ant is and couldn’t find a way to use it’s symlink 
> task, and I’m hesitant to bring node/gulp in to the project just to make some 
> symlinks.
> 
> David Jencks
> 
>> On Oct 2, 2021, at 10:17 AM, David Jencks > > wrote:
>> 
>> I always forget that for Antora terms often have a specific meaning that 
>> isn’t that common or obvious :-)
>> 
>>> On Oct 2, 2021, at 12:45 AM, Claus Ibsen >> > wrote:
>>> 
>>> On Fri, Oct 1, 2021 at 11:30 PM David Jencks >> > wrote:
 
 I looked at camel-spring-boot a little bit and have several questions and 
 suggestions… if there’s agreement I’ll open some issues and work on them.
 
 1. The AsciiDoc pages are only included in the main component/dataformat/… 
 pages, and not accessible through navigation standalone.  I think they 
 should be partials, not standalone pages.
 
>>> 
>>> You can possible not do this as the ascii doc is generated with
>>> information from spring boot itself, there are some camel spring boot
>>> started components that have spring boot auto configuration,
>>> that information are not in the camel-catalog, but are stored in
>>> spring boot style (inside the JAR in META-INF there is a spring boot
>>> json file).
>>> 
>>> 
>> 
>> This just involves moving the target location of the generated pages to 
>> modules/ROOT/partials from modules/ROOT/pages, and in main camel components 
>> changing the include::….page$... to include::….partial$…
>> This would not be a good idea if there was a firm plan to, at some point, 
>> also have this information on standalone pages, or convert the current 
>> include:: to a link to a standalone page.  Otherwise, it’s simple and 
>> shouldn’t disrupt anything. The generated spring boot docs would still be in 
>> the camel-spring-boot repo.
>> 
>>> 
 2. The individual generated pages are tied 1-1 with the ‘components’ 
 component.  I think, even though they are (at least currently) in a 
 different repo having them in the ‘components’ component as part of a 
 distributed component makes more sense than having them in a different 
 component.
 
>>> 
>>> Not sure what you mean?
>> 
>> We’d need 2 directories in camel-spring-boot docs, say
>> 
>> components/modules/spring-boot/partials  where all the individual generated 
>> pages go, with a components/antora.yml specifying name: components and 
>> version: 
>> 
>> and
>> 
>> spring-boot/modules/ROOT/pages where the 3 or 4 other non-generated pages go 
>> with the current antora.yml.
>> 
>> I think this would make it more clear that the individual generated docs 
>> actually are shown as part of the “components” component. It won’t affect 
>> Antora in any noticeable way.
>> 
>>> 
>>> 
 3. IIUC the individual pages are completely generated from data in a json 
 file.  I think this can be completely replaced with a partial and the 
 “jsonpath” stuff like we recently did for the ‘components' generated 
 content.
 (There seem to be a few that aren’t generated 

Re: [Website] camel-spring-boot docs

[David Jencks]

I went ahead and implemented the first two of these in main “latest” branches. 
Other than removing 324 unreferenced and inaccessible pages, I don’t see any 
changes (There’s one slight change to the single reference to one of the 
removed pages: (diff is new to old)

< Also add any component starters your 
Spring Boot application requires. For example this adds the auto-configuration starter for the ActiveMQ 
component.
---
> And any component starters your 
> Spring Boot application requires. For example this adds the  href="activemq-starter.html" class="page">starter for the  href="../../components/3.

(instead of linking to an otherwise inaccessible page, it links to the section 
where that content is included in the activemq component page.)

PRs:
https://github.com/apache/camel-website/pull/641 (incomplete, pending merging 
other two or 8, see below)
https://github.com/apache/camel-spring-boot/pull/374 
 (moves generated content 
to "partials" in a separate directory tree)
https://github.com/apache/camel/pull/6200 (changes includes of this content)

Since this removes a lot of pages, I’d like to apply this idea to all the 
active camel-spring-boot branches (latest, 3.12.x, 3.11.x, 3.7.x).

I was hoping to replace copying the AsciiDoc files with symlinks, but I’d 
forgotten how cantankerous Ant is and couldn’t find a way to use it’s symlink 
task, and I’m hesitant to bring node/gulp in to the project just to make some 
symlinks.

David Jencks

> On Oct 2, 2021, at 10:17 AM, David Jencks  wrote:
> 
> I always forget that for Antora terms often have a specific meaning that 
> isn’t that common or obvious :-)
> 
>> On Oct 2, 2021, at 12:45 AM, Claus Ibsen  wrote:
>> 
>> On Fri, Oct 1, 2021 at 11:30 PM David Jencks  
>> wrote:
>>> 
>>> I looked at camel-spring-boot a little bit and have several questions and 
>>> suggestions… if there’s agreement I’ll open some issues and work on them.
>>> 
>>> 1. The AsciiDoc pages are only included in the main component/dataformat/… 
>>> pages, and not accessible through navigation standalone.  I think they 
>>> should be partials, not standalone pages.
>>> 
>> 
>> You can possible not do this as the ascii doc is generated with
>> information from spring boot itself, there are some camel spring boot
>> started components that have spring boot auto configuration,
>> that information are not in the camel-catalog, but are stored in
>> spring boot style (inside the JAR in META-INF there is a spring boot
>> json file).
>> 
>> 
> 
> This just involves moving the target location of the generated pages to 
> modules/ROOT/partials from modules/ROOT/pages, and in main camel components 
> changing the include::….page$... to include::….partial$…
> This would not be a good idea if there was a firm plan to, at some point, 
> also have this information on standalone pages, or convert the current 
> include:: to a link to a standalone page.  Otherwise, it’s simple and 
> shouldn’t disrupt anything. The generated spring boot docs would still be in 
> the camel-spring-boot repo.
> 
>> 
>>> 2. The individual generated pages are tied 1-1 with the ‘components’ 
>>> component.  I think, even though they are (at least currently) in a 
>>> different repo having them in the ‘components’ component as part of a 
>>> distributed component makes more sense than having them in a different 
>>> component.
>>> 
>> 
>> Not sure what you mean?
> 
> We’d need 2 directories in camel-spring-boot docs, say
> 
> components/modules/spring-boot/partials  where all the individual generated 
> pages go, with a components/antora.yml specifying name: components and 
> version: 
> 
> and
> 
> spring-boot/modules/ROOT/pages where the 3 or 4 other non-generated pages go 
> with the current antora.yml.
> 
> I think this would make it more clear that the individual generated docs 
> actually are shown as part of the “components” component. It won’t affect 
> Antora in any noticeable way.
> 
>> 
>> 
>>> 3. IIUC the individual pages are completely generated from data in a json 
>>> file.  I think this can be completely replaced with a partial and the 
>>> “jsonpath” stuff like we recently did for the ‘components' generated 
>>> content.
>>> (There seem to be a few that aren’t generated under core, but I haven’t 
>>> found if or where they show up in the website. Perhaps some or all could be 
>>> removed?)
>>> 
>> 
>> As first response, its from spring boot json data file.
> 
> Thanks!
> 
>> 
>> 
>>> 4. Are there any components/dataformats/… that don’t participate in spring 
>>> boot? If not, what is the purpose of the table listing all the spring 
>>> boots, which points to the components pages?
>>> https://camel.apache.org/camel-spring-boot/latest/list.html
>>> If this page serves a useful purpose perhaps the table can be generated 
>>> using indexTable as in the ‘components’ component.
>>> 
>> 
>> The point is to list all the supported spring boot starters. When 

Re: [Website] camel-spring-boot docs

[David Jencks]

I always forget that for Antora terms often have a specific meaning that isn’t 
that common or obvious :-)

> On Oct 2, 2021, at 12:45 AM, Claus Ibsen  wrote:
> 
> On Fri, Oct 1, 2021 at 11:30 PM David Jencks  wrote:
>> 
>> I looked at camel-spring-boot a little bit and have several questions and 
>> suggestions… if there’s agreement I’ll open some issues and work on them.
>> 
>> 1. The AsciiDoc pages are only included in the main component/dataformat/… 
>> pages, and not accessible through navigation standalone.  I think they 
>> should be partials, not standalone pages.
>> 
> 
> You can possible not do this as the ascii doc is generated with
> information from spring boot itself, there are some camel spring boot
> started components that have spring boot auto configuration,
> that information are not in the camel-catalog, but are stored in
> spring boot style (inside the JAR in META-INF there is a spring boot
> json file).
> 
> 

This just involves moving the target location of the generated pages to 
modules/ROOT/partials from modules/ROOT/pages, and in main camel components 
changing the include::….page$... to include::….partial$…
This would not be a good idea if there was a firm plan to, at some point, also 
have this information on standalone pages, or convert the current include:: to 
a link to a standalone page.  Otherwise, it’s simple and shouldn’t disrupt 
anything. The generated spring boot docs would still be in the 
camel-spring-boot repo.

> 
>> 2. The individual generated pages are tied 1-1 with the ‘components’ 
>> component.  I think, even though they are (at least currently) in a 
>> different repo having them in the ‘components’ component as part of a 
>> distributed component makes more sense than having them in a different 
>> component.
>> 
> 
> Not sure what you mean?

We’d need 2 directories in camel-spring-boot docs, say

components/modules/spring-boot/partials  where all the individual generated 
pages go, with a components/antora.yml specifying name: components and version: 


and

spring-boot/modules/ROOT/pages where the 3 or 4 other non-generated pages go 
with the current antora.yml.

I think this would make it more clear that the individual generated docs 
actually are shown as part of the “components” component. It won’t affect 
Antora in any noticeable way.

> 
> 
>> 3. IIUC the individual pages are completely generated from data in a json 
>> file.  I think this can be completely replaced with a partial and the 
>> “jsonpath” stuff like we recently did for the ‘components' generated content.
>> (There seem to be a few that aren’t generated under core, but I haven’t 
>> found if or where they show up in the website. Perhaps some or all could be 
>> removed?)
>> 
> 
> As first response, its from spring boot json data file.

Thanks!

> 
> 
>> 4. Are there any components/dataformats/… that don’t participate in spring 
>> boot? If not, what is the purpose of the table listing all the spring boots, 
>> which points to the components pages?
>> https://camel.apache.org/camel-spring-boot/latest/list.html
>> If this page serves a useful purpose perhaps the table can be generated 
>> using indexTable as in the ‘components’ component.
>> 
> 
> The point is to list all the supported spring boot starters. When you
> use Camel with Spring Boot then use only these JARs.
> That is the "stuff" that works on Spring Boot.
> 
> We have similar for Karaf (whats in the features.xml file), and for
> Quarkus with the camel quarkus extensions.

That makes sense!

> 
> 
>> 5. These pages:
>> https://camel.apache.org/camel-spring-boot/latest/index.html
>> https://camel.apache.org/camel-spring-boot/latest/spring-boot.html
>> seem to have a lot of overlapping content.  I’m completely bewildered by the 
>> apparent duplication and don’t understand what the different choices on each 
>> page do or how they differ. I think it would be great if someone would make 
>> these docs clearer.
>> 
> 
> Yes there is a JIRA ticket to overhaul and cleanup the docs. I am
> slowing working my way through that.

A never ending task :-) at least it seems that way to me sometimes…

Many thanks!

> 
> 
>> Maybe that’s enough for now…
>> 
>> David Jencks
> 
> 
> 
> -- 
> Claus Ibsen
> -
> http://davsclaus.com @davsclaus
> Camel in Action 2: https://www.manning.com/ibsen2

Re: [Website] camel-spring-boot docs

[Claus Ibsen]

On Fri, Oct 1, 2021 at 11:30 PM David Jencks  wrote:
>
> I looked at camel-spring-boot a little bit and have several questions and 
> suggestions… if there’s agreement I’ll open some issues and work on them.
>
> 1. The AsciiDoc pages are only included in the main component/dataformat/… 
> pages, and not accessible through navigation standalone.  I think they should 
> be partials, not standalone pages.
>

You can possible not do this as the ascii doc is generated with
information from spring boot itself, there are some camel spring boot
started components that have spring boot auto configuration,
that information are not in the camel-catalog, but are stored in
spring boot style (inside the JAR in META-INF there is a spring boot
json file).



> 2. The individual generated pages are tied 1-1 with the ‘components’ 
> component.  I think, even though they are (at least currently) in a different 
> repo having them in the ‘components’ component as part of a distributed 
> component makes more sense than having them in a different component.
>

Not sure what you mean?


> 3. IIUC the individual pages are completely generated from data in a json 
> file.  I think this can be completely replaced with a partial and the 
> “jsonpath” stuff like we recently did for the ‘components' generated content.
> (There seem to be a few that aren’t generated under core, but I haven’t found 
> if or where they show up in the website. Perhaps some or all could be 
> removed?)
>

As first response, its from spring boot json data file.


> 4. Are there any components/dataformats/… that don’t participate in spring 
> boot? If not, what is the purpose of the table listing all the spring boots, 
> which points to the components pages?
> https://camel.apache.org/camel-spring-boot/latest/list.html
> If this page serves a useful purpose perhaps the table can be generated using 
> indexTable as in the ‘components’ component.
>

The point is to list all the supported spring boot starters. When you
use Camel with Spring Boot then use only these JARs.
That is the "stuff" that works on Spring Boot.

We have similar for Karaf (whats in the features.xml file), and for
Quarkus with the camel quarkus extensions.


> 5. These pages:
> https://camel.apache.org/camel-spring-boot/latest/index.html
> https://camel.apache.org/camel-spring-boot/latest/spring-boot.html
> seem to have a lot of overlapping content.  I’m completely bewildered by the 
> apparent duplication and don’t understand what the different choices on each 
> page do or how they differ. I think it would be great if someone would make 
> these docs clearer.
>

Yes there is a JIRA ticket to overhaul and cleanup the docs. I am
slowing working my way through that.


> Maybe that’s enough for now…
>
> David Jencks



-- 
Claus Ibsen
-
http://davsclaus.com @davsclaus
Camel in Action 2: https://www.manning.com/ibsen2

[Website] camel-spring-boot docs

[David Jencks]

I looked at camel-spring-boot a little bit and have several questions and 
suggestions… if there’s agreement I’ll open some issues and work on them.

1. The AsciiDoc pages are only included in the main component/dataformat/… 
pages, and not accessible through navigation standalone.  I think they should 
be partials, not standalone pages.

2. The individual generated pages are tied 1-1 with the ‘components’ component. 
 I think, even though they are (at least currently) in a different repo having 
them in the ‘components’ component as part of a distributed component makes 
more sense than having them in a different component.

3. IIUC the individual pages are completely generated from data in a json file. 
 I think this can be completely replaced with a partial and the “jsonpath” 
stuff like we recently did for the ‘components' generated content.
(There seem to be a few that aren’t generated under core, but I haven’t found 
if or where they show up in the website. Perhaps some or all could be removed?)

4. Are there any components/dataformats/… that don’t participate in spring 
boot? If not, what is the purpose of the table listing all the spring boots, 
which points to the components pages?
https://camel.apache.org/camel-spring-boot/latest/list.html
If this page serves a useful purpose perhaps the table can be generated using 
indexTable as in the ‘components’ component.

5. These pages:
https://camel.apache.org/camel-spring-boot/latest/index.html
https://camel.apache.org/camel-spring-boot/latest/spring-boot.html
seem to have a lot of overlapping content.  I’m completely bewildered by the 
apparent duplication and don’t understand what the different choices on each 
page do or how they differ. I think it would be great if someone would make 
these docs clearer.

Maybe that’s enough for now…

David Jencks