doc: fix broken relative md links #30025
pull willcl-ark wants to merge 1 commits into bitcoin:master from willcl-ark:fix-links changing 5 files +15 −16-
willcl-ark commented at 8:33 pm on May 2, 2024: memberThese relative links in our documentation are broken, fix them.
-
DrahtBot commented at 8:33 pm on May 2, 2024: contributor
The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.
Code Coverage
For detailed information about the code coverage, see the test coverage report.
Reviews
See the guideline for information on the review process.
Type Reviewers ACK ryanofsky, maflcko Concept ACK katesalazar Stale ACK ismaelsadeeq If your review is incorrectly listed, please react with 👎 to this comment and the bot will ignore it on the next update.
Conflicts
Reviewers, this pull request conflicts with the following ones:
- #30034 (ci: add markdown link check job by willcl-ark)
- #29965 (Lint: support running individual rust linters and improve subtree exclusion by davidgumberg)
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.
-
DrahtBot added the label Docs on May 2, 2024
-
in doc/design/libraries.md:98 in 8b3e86285f outdated
94@@ -95,7 +95,7 @@ class bitcoin-qt,bitcoind,bitcoin-cli,bitcoin-wallet bold 95 96 - The only thing that should depend on *libbitcoin_kernel* internally should be *libbitcoin_node*. GUI and wallet libraries *libbitcoinqt* and *libbitcoin_wallet* in particular should not depend on *libbitcoin_kernel* and the unneeded functionality it would pull in, like block validation. To the extent that GUI and wallet code need scripting and signing functionality, they should be get able it from *libbitcoin_consensus*, *libbitcoin_common*, and *libbitcoin_util*, instead of *libbitcoin_kernel*. 97 98-- GUI, node, and wallet code internal implementations should all be independent of each other, and the *libbitcoinqt*, *libbitcoin_node*, *libbitcoin_wallet* libraries should never reference each other's symbols. They should only call each other through [`src/interfaces/`](`../../src/interfaces/`) abstract interfaces. 99+- GUI, node, and wallet code internal implementations should all be independent of each other, and the *libbitcoinqt*, *libbitcoin_node*, *libbitcoin_wallet* libraries should never reference each other's symbols. They should only call each other through [`src/interfaces/`](../../src/interfaces/) abstract interfaces.
maflcko commented at 7:12 am on May 3, 2024:0- GUI, node, and wallet code internal implementations should all be independent of each other, and the *libbitcoinqt*, *libbitcoin_node*, *libbitcoin_wallet* libraries should never reference each other's symbols. They should only call each other through [`src/interfaces/`](/src/interfaces/) abstract interfaces.
nit: Might as well make it an absolute path?
willcl-ark commented at 7:28 am on May 3, 2024:I wanted to but those links a few lines above were relative so I just thought I’d leave these matching 😢
Will do it now with the other suggestion.
willcl-ark commented at 7:34 am on May 3, 2024:Done in 8e394d1d3b6ead130515222f5b34d509fff200a8in doc/developer-notes.md:1339 in 8b3e86285f outdated
1334@@ -1335,8 +1335,8 @@ Release notes should be written for any PR that: 1335 1336 Release notes should be added to a PR-specific release note file at 1337 `/doc/release-notes-<PR number>.md` to avoid conflicts between multiple PRs. 1338-All `release-notes*` files are merged into a single 1339-[/doc/release-notes.md](/doc/release-notes.md) file prior to the release. 1340+All `release-notes*` files are merged into a single `release-notes-<version>.md` file prior to the release, e.g.: 1341+[/doc/release-notes-27.0.md](release-notes/release-notes-27.0.md).
maflcko commented at 7:14 am on May 3, 2024:0All `release-notes*` files are merged into a single file prior to the release.
nit: Could remove the link, as it adds no value?
willcl-ark commented at 7:34 am on May 3, 2024:Done in 8e394d1d3b6ead130515222f5b34d509fff200a8maflcko approvedmaflcko commented at 7:14 am on May 3, 2024: memberlgtmwillcl-ark force-pushed on May 3, 2024maflcko commented at 9:22 am on May 3, 2024: memberACK 8e394d1d3b6ead130515222f5b34d509fff200a8maflcko commented at 9:23 am on May 3, 2024: memberIs there an easy way to find those?ismaelsadeeq commented at 9:29 am on May 3, 2024: memberutACK 8e394d1d3b6ead130515222f5b34d509fff200a8willcl-ark commented at 1:19 pm on May 3, 2024: memberIs there an easy way to find those?
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?
maflcko commented at 1:47 pm on May 3, 2024: memberWould 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)ryanofsky commented at 1:59 pm on May 3, 2024: contributorCode review 8e394d1d3b6ead130515222f5b34d509fff200a8
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?
maflcko commented at 2:02 pm on May 3, 2024: memberIs 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)?
willcl-ark commented at 2:06 pm on May 3, 2024: memberThe
mlc
tool seems fine with relative or absolute, so long as they resolve.nvim
seems to jump using relative or absolute links.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?
ryanofsky commented at 2:11 pm on May 3, 2024: contributorOh, 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 :wink:doc: fix broken relative md links
These relative links in our documentation are broken, fix them.
willcl-ark force-pushed on May 3, 2024willcl-ark commented at 3:14 pm on May 3, 2024: memberI 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
A rough search of *.md files shows me that we have 87 absolute links and 72 relative:
0will@ubuntu in ~/src/bitcoin on fix-links [$!?] : 🐍 (bitcoin) 1₿ rg "\]\(\/" */**.md | wc -l 287 3 4will@ubuntu in ~/src/bitcoin on fix-links [$!?] : 🐍 (bitcoin) 5₿ rg "\]\(\.\." */**.md | wc -l 672
…but it seems very reasonable to not break the documents you wrote/lead in maintaining, so I reverted those to relative in 4b9f49da2b120e81516ddc3dc577d7a2e58e02d3.
4b9f49da2b120e81516ddc3dc577d7a2e58e02d3 also fixes a broken external link to flake8 (it seems they deleted the gitlab repo entirely and moved to GitHub).
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)
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.
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)?
Yes agree, relative seems better if they are being checked.
katesalazar commented at 2:55 pm on May 4, 2024: contributorConcept ACKin test/lint/README.md:33 in 4b9f49da2b
35-| [`lint-python.py`](lint/lint-python.py) | [mypy](https://github.com/python/mypy) 36-| [`lint-python.py`](lint/lint-python.py) | [pyzmq](https://github.com/zeromq/pyzmq) 37-| [`lint-python-dead-code.py`](lint/lint-python-dead-code.py) | [vulture](https://github.com/jendrikseipp/vulture) 38-| [`lint-shell.py`](lint/lint-shell.py) | [ShellCheck](https://github.com/koalaman/shellcheck) 39-| [`lint-spelling.py`](lint/lint-spelling.py) | [codespell](https://github.com/codespell-project/codespell) 40+| [`lint-python.py`](/test/lint/lint-python.py) | [flake8](https://github.com/PyCQA/flake8)
ryanofsky commented at 4:14 pm on May 6, 2024:In commit “doc: fix broken relative md links” (4b9f49da2b120e81516ddc3dc577d7a2e58e02d3)
This is also updating the flake8 project url, not just changing links to be absolute, so could mention this in the commit message
ryanofsky approvedryanofsky commented at 4:15 pm on May 6, 2024: contributorCode review ACK 4b9f49da2b120e81516ddc3dc577d7a2e58e02d3. Thanks for the updates!DrahtBot requested review from ismaelsadeeq on May 6, 2024DrahtBot requested review from maflcko on May 6, 2024maflcko commented at 6:36 am on May 7, 2024: memberACK 4b9f49da2b120e81516ddc3dc577d7a2e58e02d3ismaelsadeeq commented at 7:53 am on May 7, 2024: memberRe ACK 4b9f49da2b120e81516ddc3dc577d7a2e58e02d3fanquake merged this on May 8, 2024fanquake closed this on May 8, 2024
github-metadata-mirror
This is a metadata mirror of the GitHub repository bitcoin/bitcoin. This site is not affiliated with GitHub. Content is generated from a GitHub metadata backup.
generated: 2024-11-21 18:12 UTC
This site is hosted by @0xB10C
More mirrored repositories can be found on mirror.b10c.me