[HEADSUP] Documentation link checker in the build

classic Classic list List threaded Threaded
10 messages Options
Reply | Threaded
Open this post in threaded view
|

[HEADSUP] Documentation link checker in the build

Zoran Regvart-2
Hi Cameleers,
I've added a `xref-validator`[1] to the `docs` module[2], this will
fail the build if there's a `xref` link in the asciidoc files (.adoc)
that cannot be resolved -- colloquially: broken link.

There's been a great effort by Nayananga our GSoC student helping with
the website on getting all the links pointing to the right places and
it's really easy to mistype a `xref` link, so that's why I've added it
as a part of the CAMEL-13589[3].

Now, you might be wondering what are `xref` links and how to prevent
them from becoming broken. For Antora, the tool that converts the
asciidoc files to html, we need to specify all links between asciidoc
files as `xref:` links, previously you might have seen `link:` being
used.

There's a good explanation of this concept of page ID in the Antora
documentation[4] and how to link between two pages using `xref:`
links[5].

For now remember that if you're pointing to the documentation within
the same Antora component, and we have two such components `manual`[6]
and `components`[7], use the form `xref:document.adoc`; and between
two Antora components use the form `xref:component::document.adoc`.

For example, the cdi.adoc is within the `components` component and
when it needs to link to a `camel-maven-archetypes.adoc` in the
`manual` component the xref needs to look like:

xref:manual::camel-maven-archetypes.adoc[Maven archetypes]

Have a look at the example[8] in the git repository.

So to test if the xrefs are valid you can run:

$ ./mvnw -f docs verify

It only takes about 1 minute or so to run.

Feel free to reach out to me if you have any questions on this.

zoran

[1] https://gitlab.com/antora/xref-validator
[2] https://github.com/apache/camel/blob/a607098a51cdde9eb87bf8dcc61c9428dd771dd4/docs/pom.xml#L85-L96
[3] https://issues.apache.org/jira/browse/CAMEL-13589
[4] https://docs.antora.org/antora/2.0/page/page-id/
[5] https://docs.antora.org/antora/2.0/asciidoc/page-to-page-xref/
[6] https://github.com/apache/camel/tree/master/docs/user-manual/modules/ROOT/pages
[7] https://github.com/apache/camel/tree/master/docs/components/modules/ROOT/pages
[8] https://github.com/apache/camel/blob/a607098a51cdde9eb87bf8dcc61c9428dd771dd4/docs/components/modules/ROOT/pages/cdi.adoc#L1071
--
Zoran Regvart
Reply | Threaded
Open this post in threaded view
|

Re: [HEADSUP] Documentation link checker in the build

Francois Papon
Well done Nayananga!

Great job!

regards,

François
[hidden email]

Le 23/07/2019 à 20:10, Zoran Regvart a écrit :

> Hi Cameleers,
> I've added a `xref-validator`[1] to the `docs` module[2], this will
> fail the build if there's a `xref` link in the asciidoc files (.adoc)
> that cannot be resolved -- colloquially: broken link.
>
> There's been a great effort by Nayananga our GSoC student helping with
> the website on getting all the links pointing to the right places and
> it's really easy to mistype a `xref` link, so that's why I've added it
> as a part of the CAMEL-13589[3].
>
> Now, you might be wondering what are `xref` links and how to prevent
> them from becoming broken. For Antora, the tool that converts the
> asciidoc files to html, we need to specify all links between asciidoc
> files as `xref:` links, previously you might have seen `link:` being
> used.
>
> There's a good explanation of this concept of page ID in the Antora
> documentation[4] and how to link between two pages using `xref:`
> links[5].
>
> For now remember that if you're pointing to the documentation within
> the same Antora component, and we have two such components `manual`[6]
> and `components`[7], use the form `xref:document.adoc`; and between
> two Antora components use the form `xref:component::document.adoc`.
>
> For example, the cdi.adoc is within the `components` component and
> when it needs to link to a `camel-maven-archetypes.adoc` in the
> `manual` component the xref needs to look like:
>
> xref:manual::camel-maven-archetypes.adoc[Maven archetypes]
>
> Have a look at the example[8] in the git repository.
>
> So to test if the xrefs are valid you can run:
>
> $ ./mvnw -f docs verify
>
> It only takes about 1 minute or so to run.
>
> Feel free to reach out to me if you have any questions on this.
>
> zoran
>
> [1] https://gitlab.com/antora/xref-validator
> [2] https://github.com/apache/camel/blob/a607098a51cdde9eb87bf8dcc61c9428dd771dd4/docs/pom.xml#L85-L96
> [3] https://issues.apache.org/jira/browse/CAMEL-13589
> [4] https://docs.antora.org/antora/2.0/page/page-id/
> [5] https://docs.antora.org/antora/2.0/asciidoc/page-to-page-xref/
> [6] https://github.com/apache/camel/tree/master/docs/user-manual/modules/ROOT/pages
> [7] https://github.com/apache/camel/tree/master/docs/components/modules/ROOT/pages
> [8] https://github.com/apache/camel/blob/a607098a51cdde9eb87bf8dcc61c9428dd771dd4/docs/components/modules/ROOT/pages/cdi.adoc#L1071
Reply | Threaded
Open this post in threaded view
|

Re: [HEADSUP] Documentation link checker in the build

jbonofre
In reply to this post by Zoran Regvart-2

Nice !

Thanks for the update.

Regards
JB

On Tuesday, July 23, 2019 20:10 CEST, Zoran Regvart <[hidden email]> wrote:
 Hi Cameleers,
I've added a `xref-validator`[1] to the `docs` module[2], this will
fail the build if there's a `xref` link in the asciidoc files (.adoc)
that cannot be resolved -- colloquially: broken link.

There's been a great effort by Nayananga our GSoC student helping with
the website on getting all the links pointing to the right places and
it's really easy to mistype a `xref` link, so that's why I've added it
as a part of the CAMEL-13589[3].

Now, you might be wondering what are `xref` links and how to prevent
them from becoming broken. For Antora, the tool that converts the
asciidoc files to html, we need to specify all links between asciidoc
files as `xref:` links, previously you might have seen `link:` being
used.

There's a good explanation of this concept of page ID in the Antora
documentation[4] and how to link between two pages using `xref:`
links[5].

For now remember that if you're pointing to the documentation within
the same Antora component, and we have two such components `manual`[6]
and `components`[7], use the form `xref:document.adoc`; and between
two Antora components use the form `xref:component::document.adoc`.

For example, the cdi.adoc is within the `components` component and
when it needs to link to a `camel-maven-archetypes.adoc` in the
`manual` component the xref needs to look like:

xref:manual::camel-maven-archetypes.adoc[Maven archetypes]

Have a look at the example[8] in the git repository.

So to test if the xrefs are valid you can run:

$ ./mvnw -f docs verify

It only takes about 1 minute or so to run.

Feel free to reach out to me if you have any questions on this.

zoran

[1] https://gitlab.com/antora/xref-validator
[2] https://github.com/apache/camel/blob/a607098a51cdde9eb87bf8dcc61c9428dd771dd4/docs/pom.xml#L85-L96
[3] https://issues.apache.org/jira/browse/CAMEL-13589
[4] https://docs.antora.org/antora/2.0/page/page-id/
[5] https://docs.antora.org/antora/2.0/asciidoc/page-to-page-xref/
[6] https://github.com/apache/camel/tree/master/docs/user-manual/modules/ROOT/pages
[7] https://github.com/apache/camel/tree/master/docs/components/modules/ROOT/pages
[8] https://github.com/apache/camel/blob/a607098a51cdde9eb87bf8dcc61c9428dd771dd4/docs/components/modules/ROOT/pages/cdi.adoc#L1071
--
Zoran Regvart


 
Reply | Threaded
Open this post in threaded view
|

Re: [HEADSUP] Documentation link checker in the build

Willem.Jiang
Administrator
In reply to this post by Zoran Regvart-2
Hi Zoran,

Thanks for the heads up, it's a great job.
I'm not sure if we can setup a git push-check-out[1] script by running
the command of "./mvnw -f docs verify" to make sure we do the clean up
work before pushing the change to the remote repository.
Any thoughts?

Willem Jiang

Twitter: willemjiang
Weibo: 姜宁willem

On Wed, Jul 24, 2019 at 2:11 AM Zoran Regvart <[hidden email]> wrote:

>
> Hi Cameleers,
> I've added a `xref-validator`[1] to the `docs` module[2], this will
> fail the build if there's a `xref` link in the asciidoc files (.adoc)
> that cannot be resolved -- colloquially: broken link.
>
> There's been a great effort by Nayananga our GSoC student helping with
> the website on getting all the links pointing to the right places and
> it's really easy to mistype a `xref` link, so that's why I've added it
> as a part of the CAMEL-13589[3].
>
> Now, you might be wondering what are `xref` links and how to prevent
> them from becoming broken. For Antora, the tool that converts the
> asciidoc files to html, we need to specify all links between asciidoc
> files as `xref:` links, previously you might have seen `link:` being
> used.
>
> There's a good explanation of this concept of page ID in the Antora
> documentation[4] and how to link between two pages using `xref:`
> links[5].
>
> For now remember that if you're pointing to the documentation within
> the same Antora component, and we have two such components `manual`[6]
> and `components`[7], use the form `xref:document.adoc`; and between
> two Antora components use the form `xref:component::document.adoc`.
>
> For example, the cdi.adoc is within the `components` component and
> when it needs to link to a `camel-maven-archetypes.adoc` in the
> `manual` component the xref needs to look like:
>
> xref:manual::camel-maven-archetypes.adoc[Maven archetypes]
>
> Have a look at the example[8] in the git repository.
>
> So to test if the xrefs are valid you can run:
>
> $ ./mvnw -f docs verify
>
> It only takes about 1 minute or so to run.
>
> Feel free to reach out to me if you have any questions on this.
>
> zoran
>
> [1] https://gitlab.com/antora/xref-validator
> [2] https://github.com/apache/camel/blob/a607098a51cdde9eb87bf8dcc61c9428dd771dd4/docs/pom.xml#L85-L96
> [3] https://issues.apache.org/jira/browse/CAMEL-13589
> [4] https://docs.antora.org/antora/2.0/page/page-id/
> [5] https://docs.antora.org/antora/2.0/asciidoc/page-to-page-xref/
> [6] https://github.com/apache/camel/tree/master/docs/user-manual/modules/ROOT/pages
> [7] https://github.com/apache/camel/tree/master/docs/components/modules/ROOT/pages
> [8] https://github.com/apache/camel/blob/a607098a51cdde9eb87bf8dcc61c9428dd771dd4/docs/components/modules/ROOT/pages/cdi.adoc#L1071
> --
> Zoran Regvart
Reply | Threaded
Open this post in threaded view
|

Re: [HEADSUP] Documentation link checker in the build

Zheng Feng
Thanks for the update and it is great job !

Willem, I think you were thinking to add the pre-push hook script to do
verifying before pushing ?

On Wed, Jul 24, 2019 at 8:55 AM Willem Jiang <[hidden email]> wrote:

> Hi Zoran,
>
> Thanks for the heads up, it's a great job.
> I'm not sure if we can setup a git push-check-out[1] script by running
> the command of "./mvnw -f docs verify" to make sure we do the clean up
> work before pushing the change to the remote repository.
> Any thoughts?
>
> Willem Jiang
>
> Twitter: willemjiang
> Weibo: 姜宁willem
>
> On Wed, Jul 24, 2019 at 2:11 AM Zoran Regvart <[hidden email]> wrote:
> >
> > Hi Cameleers,
> > I've added a `xref-validator`[1] to the `docs` module[2], this will
> > fail the build if there's a `xref` link in the asciidoc files (.adoc)
> > that cannot be resolved -- colloquially: broken link.
> >
> > There's been a great effort by Nayananga our GSoC student helping with
> > the website on getting all the links pointing to the right places and
> > it's really easy to mistype a `xref` link, so that's why I've added it
> > as a part of the CAMEL-13589[3].
> >
> > Now, you might be wondering what are `xref` links and how to prevent
> > them from becoming broken. For Antora, the tool that converts the
> > asciidoc files to html, we need to specify all links between asciidoc
> > files as `xref:` links, previously you might have seen `link:` being
> > used.
> >
> > There's a good explanation of this concept of page ID in the Antora
> > documentation[4] and how to link between two pages using `xref:`
> > links[5].
> >
> > For now remember that if you're pointing to the documentation within
> > the same Antora component, and we have two such components `manual`[6]
> > and `components`[7], use the form `xref:document.adoc`; and between
> > two Antora components use the form `xref:component::document.adoc`.
> >
> > For example, the cdi.adoc is within the `components` component and
> > when it needs to link to a `camel-maven-archetypes.adoc` in the
> > `manual` component the xref needs to look like:
> >
> > xref:manual::camel-maven-archetypes.adoc[Maven archetypes]
> >
> > Have a look at the example[8] in the git repository.
> >
> > So to test if the xrefs are valid you can run:
> >
> > $ ./mvnw -f docs verify
> >
> > It only takes about 1 minute or so to run.
> >
> > Feel free to reach out to me if you have any questions on this.
> >
> > zoran
> >
> > [1] https://gitlab.com/antora/xref-validator
> > [2]
> https://github.com/apache/camel/blob/a607098a51cdde9eb87bf8dcc61c9428dd771dd4/docs/pom.xml#L85-L96
> > [3] https://issues.apache.org/jira/browse/CAMEL-13589
> > [4] https://docs.antora.org/antora/2.0/page/page-id/
> > [5] https://docs.antora.org/antora/2.0/asciidoc/page-to-page-xref/
> > [6]
> https://github.com/apache/camel/tree/master/docs/user-manual/modules/ROOT/pages
> > [7]
> https://github.com/apache/camel/tree/master/docs/components/modules/ROOT/pages
> > [8]
> https://github.com/apache/camel/blob/a607098a51cdde9eb87bf8dcc61c9428dd771dd4/docs/components/modules/ROOT/pages/cdi.adoc#L1071
> > --
> > Zoran Regvart
>
Reply | Threaded
Open this post in threaded view
|

Re: [HEADSUP] Documentation link checker in the build

Willem.Jiang
Administrator
Yeah,that's is what I'm tallking about.

Willem Jiang

Twitter: willemjiang
Weibo: 姜宁willem

On Wed, Jul 24, 2019 at 9:22 AM Zheng Feng <[hidden email]> wrote:

>
> Thanks for the update and it is great job !
>
> Willem, I think you were thinking to add the pre-push hook script to do
> verifying before pushing ?
>
> On Wed, Jul 24, 2019 at 8:55 AM Willem Jiang <[hidden email]> wrote:
>
> > Hi Zoran,
> >
> > Thanks for the heads up, it's a great job.
> > I'm not sure if we can setup a git push-check-out[1] script by running
> > the command of "./mvnw -f docs verify" to make sure we do the clean up
> > work before pushing the change to the remote repository.
> > Any thoughts?
> >
> > Willem Jiang
> >
> > Twitter: willemjiang
> > Weibo: 姜宁willem
> >
> > On Wed, Jul 24, 2019 at 2:11 AM Zoran Regvart <[hidden email]> wrote:
> > >
> > > Hi Cameleers,
> > > I've added a `xref-validator`[1] to the `docs` module[2], this will
> > > fail the build if there's a `xref` link in the asciidoc files (.adoc)
> > > that cannot be resolved -- colloquially: broken link.
> > >
> > > There's been a great effort by Nayananga our GSoC student helping with
> > > the website on getting all the links pointing to the right places and
> > > it's really easy to mistype a `xref` link, so that's why I've added it
> > > as a part of the CAMEL-13589[3].
> > >
> > > Now, you might be wondering what are `xref` links and how to prevent
> > > them from becoming broken. For Antora, the tool that converts the
> > > asciidoc files to html, we need to specify all links between asciidoc
> > > files as `xref:` links, previously you might have seen `link:` being
> > > used.
> > >
> > > There's a good explanation of this concept of page ID in the Antora
> > > documentation[4] and how to link between two pages using `xref:`
> > > links[5].
> > >
> > > For now remember that if you're pointing to the documentation within
> > > the same Antora component, and we have two such components `manual`[6]
> > > and `components`[7], use the form `xref:document.adoc`; and between
> > > two Antora components use the form `xref:component::document.adoc`.
> > >
> > > For example, the cdi.adoc is within the `components` component and
> > > when it needs to link to a `camel-maven-archetypes.adoc` in the
> > > `manual` component the xref needs to look like:
> > >
> > > xref:manual::camel-maven-archetypes.adoc[Maven archetypes]
> > >
> > > Have a look at the example[8] in the git repository.
> > >
> > > So to test if the xrefs are valid you can run:
> > >
> > > $ ./mvnw -f docs verify
> > >
> > > It only takes about 1 minute or so to run.
> > >
> > > Feel free to reach out to me if you have any questions on this.
> > >
> > > zoran
> > >
> > > [1] https://gitlab.com/antora/xref-validator
> > > [2]
> > https://github.com/apache/camel/blob/a607098a51cdde9eb87bf8dcc61c9428dd771dd4/docs/pom.xml#L85-L96
> > > [3] https://issues.apache.org/jira/browse/CAMEL-13589
> > > [4] https://docs.antora.org/antora/2.0/page/page-id/
> > > [5] https://docs.antora.org/antora/2.0/asciidoc/page-to-page-xref/
> > > [6]
> > https://github.com/apache/camel/tree/master/docs/user-manual/modules/ROOT/pages
> > > [7]
> > https://github.com/apache/camel/tree/master/docs/components/modules/ROOT/pages
> > > [8]
> > https://github.com/apache/camel/blob/a607098a51cdde9eb87bf8dcc61c9428dd771dd4/docs/components/modules/ROOT/pages/cdi.adoc#L1071
> > > --
> > > Zoran Regvart
> >
Reply | Threaded
Open this post in threaded view
|

Re: [HEADSUP] Documentation link checker in the build

tadayosi
In reply to this post by Zoran Regvart-2
Great job Zoran and Nayananga!

Just to make sure, is now the <<xxxxx,XXXXX>> type of cross-referencing all
deprecated and should be rewritten to xref link?  Looks like there are
still a few leftovers that still use the <<xxxxx,XXXXX>> style.

Thank you,
Tadayoshi

On Wed, Jul 24, 2019 at 3:11 AM Zoran Regvart <[hidden email]> wrote:

> Hi Cameleers,
> I've added a `xref-validator`[1] to the `docs` module[2], this will
> fail the build if there's a `xref` link in the asciidoc files (.adoc)
> that cannot be resolved -- colloquially: broken link.
>
> There's been a great effort by Nayananga our GSoC student helping with
> the website on getting all the links pointing to the right places and
> it's really easy to mistype a `xref` link, so that's why I've added it
> as a part of the CAMEL-13589[3].
>
> Now, you might be wondering what are `xref` links and how to prevent
> them from becoming broken. For Antora, the tool that converts the
> asciidoc files to html, we need to specify all links between asciidoc
> files as `xref:` links, previously you might have seen `link:` being
> used.
>
> There's a good explanation of this concept of page ID in the Antora
> documentation[4] and how to link between two pages using `xref:`
> links[5].
>
> For now remember that if you're pointing to the documentation within
> the same Antora component, and we have two such components `manual`[6]
> and `components`[7], use the form `xref:document.adoc`; and between
> two Antora components use the form `xref:component::document.adoc`.
>
> For example, the cdi.adoc is within the `components` component and
> when it needs to link to a `camel-maven-archetypes.adoc` in the
> `manual` component the xref needs to look like:
>
> xref:manual::camel-maven-archetypes.adoc[Maven archetypes]
>
> Have a look at the example[8] in the git repository.
>
> So to test if the xrefs are valid you can run:
>
> $ ./mvnw -f docs verify
>
> It only takes about 1 minute or so to run.
>
> Feel free to reach out to me if you have any questions on this.
>
> zoran
>
> [1] https://gitlab.com/antora/xref-validator
> [2]
> https://github.com/apache/camel/blob/a607098a51cdde9eb87bf8dcc61c9428dd771dd4/docs/pom.xml#L85-L96
> [3] https://issues.apache.org/jira/browse/CAMEL-13589
> [4] https://docs.antora.org/antora/2.0/page/page-id/
> [5] https://docs.antora.org/antora/2.0/asciidoc/page-to-page-xref/
> [6]
> https://github.com/apache/camel/tree/master/docs/user-manual/modules/ROOT/pages
> [7]
> https://github.com/apache/camel/tree/master/docs/components/modules/ROOT/pages
> [8]
> https://github.com/apache/camel/blob/a607098a51cdde9eb87bf8dcc61c9428dd771dd4/docs/components/modules/ROOT/pages/cdi.adoc#L1071
> --
> Zoran Regvart
>
Reply | Threaded
Open this post in threaded view
|

Re: [HEADSUP] Documentation link checker in the build

tadayosi
And if I'm not mistaken, are the header IDs [[...]] such as:
https://raw.githubusercontent.com/apache/camel/master/core/camel-core/src/main/docs/eips/aggregate-eip.adoc
-----
[[aggregate-eip]]
== Aggregate EIP
...
-----
not necessary any longer as they are used only for <<...>> style of
cross-referencing?

Best regards,
Tadayoshi

On Wed, Jul 24, 2019 at 11:41 AM Tadayoshi Sato <[hidden email]>
wrote:

> Great job Zoran and Nayananga!
>
> Just to make sure, is now the <<xxxxx,XXXXX>> type of cross-referencing
> all deprecated and should be rewritten to xref link?  Looks like there are
> still a few leftovers that still use the <<xxxxx,XXXXX>> style.
>
> Thank you,
> Tadayoshi
>
> On Wed, Jul 24, 2019 at 3:11 AM Zoran Regvart <[hidden email]> wrote:
>
>> Hi Cameleers,
>> I've added a `xref-validator`[1] to the `docs` module[2], this will
>> fail the build if there's a `xref` link in the asciidoc files (.adoc)
>> that cannot be resolved -- colloquially: broken link.
>>
>> There's been a great effort by Nayananga our GSoC student helping with
>> the website on getting all the links pointing to the right places and
>> it's really easy to mistype a `xref` link, so that's why I've added it
>> as a part of the CAMEL-13589[3].
>>
>> Now, you might be wondering what are `xref` links and how to prevent
>> them from becoming broken. For Antora, the tool that converts the
>> asciidoc files to html, we need to specify all links between asciidoc
>> files as `xref:` links, previously you might have seen `link:` being
>> used.
>>
>> There's a good explanation of this concept of page ID in the Antora
>> documentation[4] and how to link between two pages using `xref:`
>> links[5].
>>
>> For now remember that if you're pointing to the documentation within
>> the same Antora component, and we have two such components `manual`[6]
>> and `components`[7], use the form `xref:document.adoc`; and between
>> two Antora components use the form `xref:component::document.adoc`.
>>
>> For example, the cdi.adoc is within the `components` component and
>> when it needs to link to a `camel-maven-archetypes.adoc` in the
>> `manual` component the xref needs to look like:
>>
>> xref:manual::camel-maven-archetypes.adoc[Maven archetypes]
>>
>> Have a look at the example[8] in the git repository.
>>
>> So to test if the xrefs are valid you can run:
>>
>> $ ./mvnw -f docs verify
>>
>> It only takes about 1 minute or so to run.
>>
>> Feel free to reach out to me if you have any questions on this.
>>
>> zoran
>>
>> [1] https://gitlab.com/antora/xref-validator
>> [2]
>> https://github.com/apache/camel/blob/a607098a51cdde9eb87bf8dcc61c9428dd771dd4/docs/pom.xml#L85-L96
>> [3] https://issues.apache.org/jira/browse/CAMEL-13589
>> [4] https://docs.antora.org/antora/2.0/page/page-id/
>> [5] https://docs.antora.org/antora/2.0/asciidoc/page-to-page-xref/
>> [6]
>> https://github.com/apache/camel/tree/master/docs/user-manual/modules/ROOT/pages
>> [7]
>> https://github.com/apache/camel/tree/master/docs/components/modules/ROOT/pages
>> [8]
>> https://github.com/apache/camel/blob/a607098a51cdde9eb87bf8dcc61c9428dd771dd4/docs/components/modules/ROOT/pages/cdi.adoc#L1071
>> --
>> Zoran Regvart
>>
>
Reply | Threaded
Open this post in threaded view
|

Re: [HEADSUP] Documentation link checker in the build

Zoran Regvart-2
In reply to this post by Willem.Jiang
Hi Willem
+1 I like automating things and having computers tell me when I mess
up, so having a pre-commit check git hook could help with that. I'm
not sure if the added latency to git commit might be a problem for
someone.

zoran

On Wed, Jul 24, 2019 at 2:55 AM Willem Jiang <[hidden email]> wrote:

>
> Hi Zoran,
>
> Thanks for the heads up, it's a great job.
> I'm not sure if we can setup a git push-check-out[1] script by running
> the command of "./mvnw -f docs verify" to make sure we do the clean up
> work before pushing the change to the remote repository.
> Any thoughts?
>
> Willem Jiang
>
> Twitter: willemjiang
> Weibo: 姜宁willem
>
> On Wed, Jul 24, 2019 at 2:11 AM Zoran Regvart <[hidden email]> wrote:
> >
> > Hi Cameleers,
> > I've added a `xref-validator`[1] to the `docs` module[2], this will
> > fail the build if there's a `xref` link in the asciidoc files (.adoc)
> > that cannot be resolved -- colloquially: broken link.
> >
> > There's been a great effort by Nayananga our GSoC student helping with
> > the website on getting all the links pointing to the right places and
> > it's really easy to mistype a `xref` link, so that's why I've added it
> > as a part of the CAMEL-13589[3].
> >
> > Now, you might be wondering what are `xref` links and how to prevent
> > them from becoming broken. For Antora, the tool that converts the
> > asciidoc files to html, we need to specify all links between asciidoc
> > files as `xref:` links, previously you might have seen `link:` being
> > used.
> >
> > There's a good explanation of this concept of page ID in the Antora
> > documentation[4] and how to link between two pages using `xref:`
> > links[5].
> >
> > For now remember that if you're pointing to the documentation within
> > the same Antora component, and we have two such components `manual`[6]
> > and `components`[7], use the form `xref:document.adoc`; and between
> > two Antora components use the form `xref:component::document.adoc`.
> >
> > For example, the cdi.adoc is within the `components` component and
> > when it needs to link to a `camel-maven-archetypes.adoc` in the
> > `manual` component the xref needs to look like:
> >
> > xref:manual::camel-maven-archetypes.adoc[Maven archetypes]
> >
> > Have a look at the example[8] in the git repository.
> >
> > So to test if the xrefs are valid you can run:
> >
> > $ ./mvnw -f docs verify
> >
> > It only takes about 1 minute or so to run.
> >
> > Feel free to reach out to me if you have any questions on this.
> >
> > zoran
> >
> > [1] https://gitlab.com/antora/xref-validator
> > [2] https://github.com/apache/camel/blob/a607098a51cdde9eb87bf8dcc61c9428dd771dd4/docs/pom.xml#L85-L96
> > [3] https://issues.apache.org/jira/browse/CAMEL-13589
> > [4] https://docs.antora.org/antora/2.0/page/page-id/
> > [5] https://docs.antora.org/antora/2.0/asciidoc/page-to-page-xref/
> > [6] https://github.com/apache/camel/tree/master/docs/user-manual/modules/ROOT/pages
> > [7] https://github.com/apache/camel/tree/master/docs/components/modules/ROOT/pages
> > [8] https://github.com/apache/camel/blob/a607098a51cdde9eb87bf8dcc61c9428dd771dd4/docs/components/modules/ROOT/pages/cdi.adoc#L1071
> > --
> > Zoran Regvart



--
Zoran Regvart
Reply | Threaded
Open this post in threaded view
|

Re: [HEADSUP] Documentation link checker in the build

Zoran Regvart-2
In reply to this post by tadayosi
Hi Tadayoshi,
this is only for when you want to link from one document to the next,
for within document links using the <<..>> style is fine.

Take a look at the Antora documentation[1] for a better explanation.

zoran

[1] https://docs.antora.org/antora/2.0/asciidoc/in-page-xref/

On Wed, Jul 24, 2019 at 4:47 AM Tadayoshi Sato <[hidden email]> wrote:

>
> And if I'm not mistaken, are the header IDs [[...]] such as:
> https://raw.githubusercontent.com/apache/camel/master/core/camel-core/src/main/docs/eips/aggregate-eip.adoc
> -----
> [[aggregate-eip]]
> == Aggregate EIP
> ...
> -----
> not necessary any longer as they are used only for <<...>> style of
> cross-referencing?
>
> Best regards,
> Tadayoshi
>
> On Wed, Jul 24, 2019 at 11:41 AM Tadayoshi Sato <[hidden email]>
> wrote:
>
> > Great job Zoran and Nayananga!
> >
> > Just to make sure, is now the <<xxxxx,XXXXX>> type of cross-referencing
> > all deprecated and should be rewritten to xref link?  Looks like there are
> > still a few leftovers that still use the <<xxxxx,XXXXX>> style.
> >
> > Thank you,
> > Tadayoshi
> >
> > On Wed, Jul 24, 2019 at 3:11 AM Zoran Regvart <[hidden email]> wrote:
> >
> >> Hi Cameleers,
> >> I've added a `xref-validator`[1] to the `docs` module[2], this will
> >> fail the build if there's a `xref` link in the asciidoc files (.adoc)
> >> that cannot be resolved -- colloquially: broken link.
> >>
> >> There's been a great effort by Nayananga our GSoC student helping with
> >> the website on getting all the links pointing to the right places and
> >> it's really easy to mistype a `xref` link, so that's why I've added it
> >> as a part of the CAMEL-13589[3].
> >>
> >> Now, you might be wondering what are `xref` links and how to prevent
> >> them from becoming broken. For Antora, the tool that converts the
> >> asciidoc files to html, we need to specify all links between asciidoc
> >> files as `xref:` links, previously you might have seen `link:` being
> >> used.
> >>
> >> There's a good explanation of this concept of page ID in the Antora
> >> documentation[4] and how to link between two pages using `xref:`
> >> links[5].
> >>
> >> For now remember that if you're pointing to the documentation within
> >> the same Antora component, and we have two such components `manual`[6]
> >> and `components`[7], use the form `xref:document.adoc`; and between
> >> two Antora components use the form `xref:component::document.adoc`.
> >>
> >> For example, the cdi.adoc is within the `components` component and
> >> when it needs to link to a `camel-maven-archetypes.adoc` in the
> >> `manual` component the xref needs to look like:
> >>
> >> xref:manual::camel-maven-archetypes.adoc[Maven archetypes]
> >>
> >> Have a look at the example[8] in the git repository.
> >>
> >> So to test if the xrefs are valid you can run:
> >>
> >> $ ./mvnw -f docs verify
> >>
> >> It only takes about 1 minute or so to run.
> >>
> >> Feel free to reach out to me if you have any questions on this.
> >>
> >> zoran
> >>
> >> [1] https://gitlab.com/antora/xref-validator
> >> [2]
> >> https://github.com/apache/camel/blob/a607098a51cdde9eb87bf8dcc61c9428dd771dd4/docs/pom.xml#L85-L96
> >> [3] https://issues.apache.org/jira/browse/CAMEL-13589
> >> [4] https://docs.antora.org/antora/2.0/page/page-id/
> >> [5] https://docs.antora.org/antora/2.0/asciidoc/page-to-page-xref/
> >> [6]
> >> https://github.com/apache/camel/tree/master/docs/user-manual/modules/ROOT/pages
> >> [7]
> >> https://github.com/apache/camel/tree/master/docs/components/modules/ROOT/pages
> >> [8]
> >> https://github.com/apache/camel/blob/a607098a51cdde9eb87bf8dcc61c9428dd771dd4/docs/components/modules/ROOT/pages/cdi.adoc#L1071
> >> --
> >> Zoran Regvart
> >>
> >



--
Zoran Regvart