Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Emit new digest file with all web URLs encountered in the content #701

Open
amartini51 opened this issue Aug 21, 2023 · 2 comments
Open

Emit new digest file with all web URLs encountered in the content #701

amartini51 opened this issue Aug 21, 2023 · 2 comments

Comments

@amartini51
Copy link
Member

Feature Name

URL destination checking

Description

I recently found and fixed a number of broken links from The Swift Programming Language (TSPL) to the Swift standard library documentation. As far as I can tell, DocC doesn't currently have a way to detect dead links, so I built a script by hand using cmark and curl to check for this in the TSPL build script.

This seems like functionality that other projects besides TSPL could use, so it would be beneficial to incorporate it as a diagnostic for DocC. Because checking the validity of links takes time and requires a network connection, it's probably something that should be opt-in.

Motivation

No response

Importance

No response

Alternatives Considered

No response
@amartini51 amartini51 added the enhancement Improvements or enhancements to existing functionality label Aug 21, 2023
@amartini51
Copy link
Member Author

For reference, here's what I added to the TSPL preflight script:

cmark --to xml TSPL.docc/*/*.md |
xpath -q -n -e '//link/@destination' |
sort -u | cut -f2 -d= | grep -v '^"doc:' | sed 's/^"//; s/"$//' |
while read url
do
    if curl --silent --output /dev/null --fail --head $url
    then
        echo "     $url"
    else
        echo "BAD: $url"
        exit_status=1
    fi
done

@d-ronnqvist d-ronnqvist added wontfix This will not be worked on and removed enhancement Improvements or enhancements to existing functionality wontfix This will not be worked on labels Dec 21, 2023
@d-ronnqvist
Copy link
Contributor

I would argue that making web requests to verify that web links aren't broken is not something that DocC itself should do.

The specific issue with links to the Swift standard library would probably be better solved by #208 or #419.

What we could possibly do is create another opt-in digest file with all web links in the content so that other scripts don't need to parse the markdown, in-source comments, and tutorial files to find all the links themselves.

@d-ronnqvist d-ronnqvist changed the title Add the ability to emit a diagnostic for broken URL links Emit new digest file with all web URLs encountered in the content Dec 21, 2023
@heckj heckj mentioned this issue Mar 7, 2024
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@d-ronnqvist @amartini51