[0/2] Documentation/linkcheck fixes
mbox series

Message ID 20250725172130.2218836-1-kieran.bingham@ideasonboard.com
Headers show
Series
  • Documentation/linkcheck fixes
Related show

Message

Kieran Bingham July 25, 2025, 5:21 p.m. UTC
The doxygen build contains a tool to verify links are still valid.

Running this tool presently reports several issues fixed by this series.

You can run it too with:

  ninja -C build/gcc/ Documentation/linkcheck

And I've started an update to the CI to introduce including this -
however we can't merge that yet - because one of the documents is harder
to fix than the others.

Documentation/guides/tracing.rst references
https://lttng.org/docs/#doc-tracing-your-own-user-application and
https://lttng.org/docs/#doc-viewing-and-analyzing-your-traces-bt which
seem to be valid URL anchors in a web browser but the tooling reports
them as invalid. I suspect they may be generated after page load with
javascript or such that the tooling does not comprehend.

Anyway, perhaps the fixes to pipeline handler and application guides are
still worth merging first.


Kieran Bingham (2):
  Documentation: pipeline-handler: Fix broken links
  Documentation: application: Update mediactl URL

 Documentation/guides/application-developer.rst |  2 +-
 Documentation/guides/pipeline-handler.rst      | 12 ++++++------
 2 files changed, 7 insertions(+), 7 deletions(-)

Comments

Barnabás Pőcze Aug. 4, 2025, 8:22 a.m. UTC | #1
Hi

2025. 07. 25. 19:21 keltezéssel, Kieran Bingham írta:
> The doxygen build contains a tool to verify links are still valid.
> 
> Running this tool presently reports several issues fixed by this series.
> 
> You can run it too with:
> 
>    ninja -C build/gcc/ Documentation/linkcheck
> 
> And I've started an update to the CI to introduce including this -
> however we can't merge that yet - because one of the documents is harder
> to fix than the others.
> 
> Documentation/guides/tracing.rst references
> https://lttng.org/docs/#doc-tracing-your-own-user-application and
> https://lttng.org/docs/#doc-viewing-and-analyzing-your-traces-bt which
> seem to be valid URL anchors in a web browser but the tooling reports
> them as invalid. I suspect they may be generated after page load with
> javascript or such that the tooling does not comprehend.

The cause appears to be that it redirects to https://lttng.org/docs/v2.13/
using javascript. Otherwise I think it would work.

Regards,
Barnabás Pőcze


> 
> Anyway, perhaps the fixes to pipeline handler and application guides are
> still worth merging first.
> 
> 
> Kieran Bingham (2):
>    Documentation: pipeline-handler: Fix broken links
>    Documentation: application: Update mediactl URL
> 
>   Documentation/guides/application-developer.rst |  2 +-
>   Documentation/guides/pipeline-handler.rst      | 12 ++++++------
>   2 files changed, 7 insertions(+), 7 deletions(-)
>
Barnabás Pőcze Aug. 4, 2025, 8:56 a.m. UTC | #2
2025. 08. 04. 10:22 keltezéssel, Barnabás Pőcze írta:
> Hi
> 
> 2025. 07. 25. 19:21 keltezéssel, Kieran Bingham írta:
>> The doxygen build contains a tool to verify links are still valid.
>>
>> Running this tool presently reports several issues fixed by this series.
>>
>> You can run it too with:
>>
>>    ninja -C build/gcc/ Documentation/linkcheck
>>
>> And I've started an update to the CI to introduce including this -
>> however we can't merge that yet - because one of the documents is harder
>> to fix than the others.
>>
>> Documentation/guides/tracing.rst references
>> https://lttng.org/docs/#doc-tracing-your-own-user-application and
>> https://lttng.org/docs/#doc-viewing-and-analyzing-your-traces-bt which
>> seem to be valid URL anchors in a web browser but the tooling reports
>> them as invalid. I suspect they may be generated after page load with
>> javascript or such that the tooling does not comprehend.
> 
> The cause appears to be that it redirects to https://lttng.org/docs/v2.13/
> using javascript. Otherwise I think it would work.

Or one could set

   linkcheck_anchors_ignore_for_url = (
       'https://lttng.org/docs/',
   )

in the sphinx configuration and then they pass the check.


> 
> Regards,
> Barnabás Pőcze
> 
> 
>>
>> Anyway, perhaps the fixes to pipeline handler and application guides are
>> still worth merging first.
>>
>>
>> Kieran Bingham (2):
>>    Documentation: pipeline-handler: Fix broken links
>>    Documentation: application: Update mediactl URL
>>
>>   Documentation/guides/application-developer.rst |  2 +-
>>   Documentation/guides/pipeline-handler.rst      | 12 ++++++------
>>   2 files changed, 7 insertions(+), 7 deletions(-)
>>
>
Laurent Pinchart Aug. 4, 2025, 9:51 p.m. UTC | #3
On Mon, Aug 04, 2025 at 10:56:33AM +0200, Barnabás Pőcze wrote:
> 2025. 08. 04. 10:22 keltezéssel, Barnabás Pőcze írta:
> > 2025. 07. 25. 19:21 keltezéssel, Kieran Bingham írta:
> >> The doxygen build contains a tool to verify links are still valid.
> >>
> >> Running this tool presently reports several issues fixed by this series.
> >>
> >> You can run it too with:
> >>
> >>    ninja -C build/gcc/ Documentation/linkcheck
> >>
> >> And I've started an update to the CI to introduce including this -
> >> however we can't merge that yet - because one of the documents is harder
> >> to fix than the others.
> >>
> >> Documentation/guides/tracing.rst references
> >> https://lttng.org/docs/#doc-tracing-your-own-user-application and
> >> https://lttng.org/docs/#doc-viewing-and-analyzing-your-traces-bt which
> >> seem to be valid URL anchors in a web browser but the tooling reports
> >> them as invalid. I suspect they may be generated after page load with
> >> javascript or such that the tooling does not comprehend.
> > 
> > The cause appears to be that it redirects to https://lttng.org/docs/v2.13/
> > using javascript. Otherwise I think it would work.

Damn javascript. Everybody should use lynx, that would solve many of our
issues :-)

> Or one could set
> 
>    linkcheck_anchors_ignore_for_url = (
>        'https://lttng.org/docs/',
>    )

That defeats the point of link checks a little bit, but if that's the
best we can do... I wonder if it's worth contacting lttng to ask them to
use an HTTP redirection.

> in the sphinx configuration and then they pass the check.
> 
> >> Anyway, perhaps the fixes to pipeline handler and application guides are
> >> still worth merging first.
> >>
> >>
> >> Kieran Bingham (2):
> >>    Documentation: pipeline-handler: Fix broken links
> >>    Documentation: application: Update mediactl URL
> >>
> >>   Documentation/guides/application-developer.rst |  2 +-
> >>   Documentation/guides/pipeline-handler.rst      | 12 ++++++------
> >>   2 files changed, 7 insertions(+), 7 deletions(-)
Laurent Pinchart Aug. 4, 2025, 10:33 p.m. UTC | #4
On Tue, Aug 05, 2025 at 12:51:49AM +0300, Laurent Pinchart wrote:
> On Mon, Aug 04, 2025 at 10:56:33AM +0200, Barnabás Pőcze wrote:
> > 2025. 08. 04. 10:22 keltezéssel, Barnabás Pőcze írta:
> > > 2025. 07. 25. 19:21 keltezéssel, Kieran Bingham írta:
> > >> The doxygen build contains a tool to verify links are still valid.
> > >>
> > >> Running this tool presently reports several issues fixed by this series.
> > >>
> > >> You can run it too with:
> > >>
> > >>    ninja -C build/gcc/ Documentation/linkcheck
> > >>
> > >> And I've started an update to the CI to introduce including this -
> > >> however we can't merge that yet - because one of the documents is harder
> > >> to fix than the others.
> > >>
> > >> Documentation/guides/tracing.rst references
> > >> https://lttng.org/docs/#doc-tracing-your-own-user-application and
> > >> https://lttng.org/docs/#doc-viewing-and-analyzing-your-traces-bt which
> > >> seem to be valid URL anchors in a web browser but the tooling reports
> > >> them as invalid. I suspect they may be generated after page load with
> > >> javascript or such that the tooling does not comprehend.
> > > 
> > > The cause appears to be that it redirects to https://lttng.org/docs/v2.13/
> > > using javascript. Otherwise I think it would work.
> 
> Damn javascript. Everybody should use lynx, that would solve many of our
> issues :-)
> 
> > Or one could set
> > 
> >    linkcheck_anchors_ignore_for_url = (
> >        'https://lttng.org/docs/',
> >    )
> 
> That defeats the point of link checks a little bit, but if that's the
> best we can do... I wonder if it's worth contacting lttng to ask them to
> use an HTTP redirection.

Apparently we have another issue: the relative links generated by
doxylink are not handled nicely by linkcheck. The linkcheck builder
tries to resolve all relative files path based on the path to the Sphinx
source document, while they should be relative to the generated html
documents. One option could be to pass a custom conf.py to set different
relative paths when using linkcheck.

> > in the sphinx configuration and then they pass the check.
> > 
> > >> Anyway, perhaps the fixes to pipeline handler and application guides are
> > >> still worth merging first.
> > >>
> > >>
> > >> Kieran Bingham (2):
> > >>    Documentation: pipeline-handler: Fix broken links
> > >>    Documentation: application: Update mediactl URL
> > >>
> > >>   Documentation/guides/application-developer.rst |  2 +-
> > >>   Documentation/guides/pipeline-handler.rst      | 12 ++++++------
> > >>   2 files changed, 7 insertions(+), 7 deletions(-)