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.
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
doc: fix broken relative md links #30025
Conversation
The following sections might be updated with supplementary metadata relevant to reviewers and maintainers. Code CoverageFor detailed information about the code coverage, see the test coverage report. ReviewsSee the guideline for information on the review process.
If your review is incorrectly listed, please react with 👎 to this comment and the bot will ignore it on the next update. ConflictsReviewers, this pull request conflicts with the following ones:
If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
lgtm
ACK 8e394d1 |
Is there an easy way to find those? |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
utACK 8e394d1
I was using this https://github.com/becheran/mlc/ in offline mode to find broken internal links. I'm sure it wouldn't take much to modify it to surface relative links, if we want them all absolute? |
Would it be easy to add mlc (or something like it) to the lint CI task? (Just as an idea for a follow-up, not for here) |
Code review 8e394d1 I don't think it is good to change these to absolute links. When I open these files in emacs I can click the relative links it will load the target files. If I change the links to be absolute, it tries to open non-existent paths on my root file system. I imagine emacs is not the only tool which behaves this way. Is it necessary to make links absolute for broken link detection to work, or some other motivation to make them absolute? |
I brought it up, because absolute paths are already used, and it makes it more robust if a file or paragraph is moved. However, if mlc (or similar) is added in the future and checks against this, relative paths should be fine (and maybe preferred, if that helps with emacs)? |
The
I did check to see if one or the other was more markdown-compliant, but it seems they purposefully avoided specifying. Seems like here we might prefer relative so we cater to emacs users, all other things being equal? |
Oh, ok. I wasn't aware absolute links were already being used. I would slightly prefer links in the two files I wrote (libraries.md and multiprocess.md) to be relative so they work with emacs and so links within the files use a consistent style. But since I am the one responsible for a lot of these broken links, don't weigh my opinion too heavily 😉 |
These relative links in our documentation are broken, fix them.
A rough search of *.md files shows me that we have 87 absolute links and 72 relative: Detailswill@ubuntu in ~/src/bitcoin on fix-links [$!?] : 🐍 (bitcoin)
₿ rg "\]\(\/" */**.md | wc -l
87
will@ubuntu in ~/src/bitcoin on fix-links [$!?] : 🐍 (bitcoin)
₿ rg "\]\(\.\." */**.md | wc -l
72 ...but it seems very reasonable to not break the documents you wrote/lead in maintaining, so I reverted those to relative in 4b9f49d. 4b9f49d also fixes a broken external link to flake8 (it seems they deleted the gitlab repo entirely and moved to GitHub).
Yes it should be; I already had a second commit in this branch to run this as a GHA but dropped it (as I thought these are quite unlikely to break regularly). I could open a PR to have this GHA run scheduled weekly (or something like that) if there's interest.
Yes agree, relative seems better if they are being checked. |
Concept ACK |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Code review ACK 4b9f49d. Thanks for the updates!
| [`lint-python-dead-code.py`](lint/lint-python-dead-code.py) | [vulture](https://github.com/jendrikseipp/vulture) | ||
| [`lint-shell.py`](lint/lint-shell.py) | [ShellCheck](https://github.com/koalaman/shellcheck) | ||
| [`lint-spelling.py`](lint/lint-spelling.py) | [codespell](https://github.com/codespell-project/codespell) | ||
| [`lint-python.py`](/test/lint/lint-python.py) | [flake8](https://github.com/PyCQA/flake8) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In commit "doc: fix broken relative md links" (4b9f49d)
This is also updating the flake8 project url, not just changing links to be absolute, so could mention this in the commit message
ACK 4b9f49d |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Re ACK 4b9f49d
These relative links in our documentation are broken, fix them.