doc: fix broken relative md links

willcl-ark commented at 8:33 pm on May 2, 2024: member

These 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 8e394d1d3b6ead130515222f5b34d509fff200a8

in 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 8e394d1d3b6ead130515222f5b34d509fff200a8

maflcko approved

maflcko commented at 7:14 am on May 3, 2024: member

lgtm

willcl-ark force-pushed on May 3, 2024

maflcko commented at 9:22 am on May 3, 2024: member

ACK 8e394d1d3b6ead130515222f5b34d509fff200a8

maflcko commented at 9:23 am on May 3, 2024: member

Is there an easy way to find those?

ismaelsadeeq commented at 9:29 am on May 3, 2024: member

utACK 8e394d1d3b6ead130515222f5b34d509fff200a8

willcl-ark commented at 1:19 pm on May 3, 2024: member

Is 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: member

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)

ryanofsky commented at 1:59 pm on May 3, 2024: contributor

Code 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: member

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)?

willcl-ark commented at 2:06 pm on May 3, 2024: member

The 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: contributor

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 :wink:

doc: fix broken relative md links

These relative links in our documentation are broken, fix them.

4b9f49da2b

willcl-ark force-pushed on May 3, 2024

willcl-ark commented at 3:14 pm on May 3, 2024: member

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

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: contributor

Concept ACK

in 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 approved

ryanofsky commented at 4:15 pm on May 6, 2024: contributor

Code review ACK 4b9f49da2b120e81516ddc3dc577d7a2e58e02d3. Thanks for the updates!

DrahtBot requested review from ismaelsadeeq on May 6, 2024

DrahtBot requested review from maflcko on May 6, 2024

maflcko commented at 6:36 am on May 7, 2024: member

ACK 4b9f49da2b120e81516ddc3dc577d7a2e58e02d3

ismaelsadeeq commented at 7:53 am on May 7, 2024: member

Re ACK 4b9f49da2b120e81516ddc3dc577d7a2e58e02d3

fanquake merged this on May 8, 2024

fanquake closed this on May 8, 2024

doc: fix broken relative md links #30025

Code Coverage

Reviews

Conflicts