Re: camel-website - documentation with links (xref) - how to do that?

[David Jencks <da...@gmail.com>]

I wrote something up on this, https://github.com/apache/camel-website/pull/608

Comments?

David Jencks

> On Apr 14, 2021, at 11:26 PM, David Jencks <da...@gmail.com> wrote:
> 
> I would explain this by relating the Antora component/module structure to the camel documentation source locations.
> 
> David Jencks 
> 
> Sent from my iPhone
> 
>> On Apr 14, 2021, at 10:29 PM, Claus Ibsen <cl...@gmail.com> wrote:
>> 
>> On Wed, Apr 14, 2021 at 9:12 PM Zoran Regvart <zo...@regvart.com> wrote:
>>> 
>>> Hi,
>>> I can point to the documentation available at Antora:
>>> 
>>> https://docs.antora.org/antora/2.3/page/page-id/#whats-a-cross-reference
>>> 
>>> Is this what you had in mind?
>>> 
>> 
>> Yes this helps to explain what is xref, and its structure.
>> 
>> However what would help alot is that we have some examples how to use
>> xref with our website and docs.
>> 
>> How to link to a component
>> How to link to an eip
>> How to link to a faq
>> How to link to a user guide doc
>> How to link to an architecture doc
>> How to link from Camel core to a Camel sub project like camel-k or
>> camel-quarkus, etc.
>> How to link from Camel sub project to core Camel
>> 
>> And when to a version (latest) or not. Some places have latest and
>> others don't etc.
>> 
>> And then maybe there is a build problem? When building the docs of the
>> Camel core project then xref checker runs, and reports errors.
>> You can also have this pass, and then errors reported when building
>> the camel-website, which you can see on the Apache CI server output.
>> 
>> 
>> 
>> 
>> 
>> 
>> 
>>> 
>>>> On Wed, Apr 14, 2021 at 9:02 AM Claus Ibsen <cl...@gmail.com> wrote:
>>>> 
>>>> Hi
>>>> 
>>>> The new website is great, but one issue is that many of us are bitten
>>>> every time we add new documentation and want to add cross links (xref)
>>>> between the pages.
>>>> 
>>>> What I think we need is a bit of explanation of how this works, and
>>>> what links you can do, and with examples
>>>> 
>>>> I created a JIRA ticket and took the liberty to assign it to Zoran (he
>>>> has the best knowledge of this)
>>>> https://issues.apache.org/jira/browse/CAMEL-16499
>>>> 
>>>> The docs we have are scattered
>>>> 
>>>> - core/camel-core-model/src/main/docs.     (eip docs)
>>>> - components/.../src/main/docs    (component docs)
>>>> - docs. (docs for camel)
>>>> - camel-website
>>>> 
>>>> And the other sub projects (camel-k, camel-spring-boot, camel-quarkus,
>>>> etc.) also have their own doc structure.
>>>> 
>>>> 
>>>> 
>>>> 
>>>> --
>>>> Claus Ibsen
>>>> -----------------
>>>> http://davsclaus.com @davsclaus
>>>> Camel in Action 2: https://www.manning.com/ibsen2
>>> 
>>> 
>>> 
>>> --
>>> Zoran Regvart
>> 
>> 
>> 
>> -- 
>> Claus Ibsen
>> -----------------
>> http://davsclaus.com @davsclaus
>> Camel in Action 2: https://www.manning.com/ibsen2