Internal code check - find non-active documentation links

Created on 23 August 2024, 4 months ago
Updated 10 September 2024, 3 months ago

Problem/Motivation

When updating documentation it is easy to copy and paste a url to an external site, for example a gitlab help page. The link is rendered as a clickable active link when previewing the changes before commit, and also when browsing the fork repository after committing to the MR.

However, when the MR is merged and the documentation page is rebuilt by MKdocs, the plain url is left as ordinary text and is not clickable. This requires a subsequent commit to fix it, and it would be nice to have this error highlighted in the 'Check Code' job, so it can be fixed before merging.

Proposed resolution

Add a script in the 'Check Code' job to locate any url which is not coded using the required [text to show](url to link to) syntax

📌 Task
Status

Fixed

Component

gitlab-ci

Created by

🇬🇧United Kingdom jonathan1055

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Merge Requests

Comments & Activities

  • Issue created by @jonathan1055
  • 🇬🇧United Kingdom jonathan1055

    Here's my first attempt at this. It finds all 'http' which do not have '(' immediatelt preceding it. So it currently fails because there are valid places in the doc pages where we have this. I am not sure how to cater for those yet.

    Currently using a script but could convert to php.

  • Merge request !251#3469949 Check for unformatted http links → (Merged) created by jonathan1055
  • Pipeline finished with Failed
    4 months ago
    Total: 114s
    #263561
  • Pipeline finished with Failed
    4 months ago
    Total: 93s
    #263567
  • Status changed to Needs review 4 months ago
  • 🇬🇧United Kingdom jonathan1055

    The 'check code' job now fails as required, with the return code detected. But the problem is what to do with the valid http text which does not need to be formatted. Maybe we can have an inline hideen comment to indicate that these can be ignored, similar to cspell:ignore or phpcs:ignore

    Another thing iI noticed if the that grep -r displays the filename locally, but this does not do the same in the pipeline, and the filename is not shown. See attached.

  • Pipeline finished with Failed
    4 months ago
    Total: 174s
    #263571
  • Pipeline finished with Failed
    4 months ago
    Total: 153s
    #263595
  • Pipeline finished with Failed
    4 months ago
    Total: 111s
    #264082
  • Pipeline finished with Failed
    4 months ago
    Total: 116s
    #264086
  • Pipeline finished with Failed
    4 months ago
    Total: 49s
    #264105
  • Pipeline finished with Failed
    4 months ago
    Total: 50s
    #264109
  • Pipeline finished with Failed
    4 months ago
    #264114
  • Pipeline finished with Failed
    4 months ago
    Total: 50s
    #264136
  • 🇬🇧United Kingdom jonathan1055

    I re-wrote the script in PHP to cater for the code blocks which will validly have plain http links.

    Test showing just two non-formatted links (one in the PHPStan page that was missed and is not clickable, and the other I reverted from your fix)
    https://git.drupalcode.org/issue/gitlab_templates-3469949/-/jobs/2545749

    Here is the passing job. PHPStan link formatted, and the tags link deleted (as it was already linked further up that page)
    https://git.drupalcode.org/issue/gitlab_templates-3469949/-/jobs/2545879

    Ready for review.

  • First commit to issue fork.
  • Status changed to RTBC 4 months ago
  • 🇪🇸Spain fjgarlin

    The script looks good and the output is very clear too. Thanks for this.
    RTBC.

    Do you need to revert the text that seems to be removed in the MR or is it really not needed?
    I'll let you either fix it or comment here with whatever is next. The script looks good and we can start using it as it is an internal tool.

  • 🇬🇧United Kingdom jonathan1055

    The text I removed is not needed, as the link was already in that same page further up. (see second part of the comment in #5)

    Have you tried running < code?./scripts/run-local-checks.sh with this chnage? It works for me, but would be good to make sure it works for you too.

    The log output just lists the unformatted links. Does it also need to say a one-liner about how to fix the listed problems. Someone other than you or me might be using it.

  • Status changed to Needs work 4 months ago
  • 🇪🇸Spain fjgarlin

    Yeah, I ran the script and it ran well. I also tried forcing an error and it found it.

    Good point about the feedback on how to fix them. Happy for you to do that commit and it can go straight back to RTBC.

  • Pipeline finished with Failed
    4 months ago
    Total: 52s
    #264978
  • Status changed to RTBC 4 months ago
  • 🇬🇧United Kingdom jonathan1055

    Pushed one line change.
    https://git.drupalcode.org/project/gitlab_templates/-/merge_requests/251...

    The text is only written if there are any faults found. Example attached.

  • Pipeline finished with Skipped
    4 months ago
    #265795
  • Status changed to Fixed 4 months ago
  • 🇪🇸Spain fjgarlin

    Merged. Thanks so much!

  • Automatically closed - issue fixed for 2 weeks with no activity.

Production build 0.71.5 2024