akiomik / akiomik/bela-rs

Links out of the package dangle on crates.io, and the rule for them is stated but not followed

Aperta
#159 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
documentation
Lingua principale
Rust
Stelle
1
Fork
0
Merge medio
5h 19m
PR unite (30g)
26

Descrizione

`bela-sys/Cargo.toml` and `bela/Cargo.toml` both set `readme = "README.md"`, so both files are rendered on crates.io with no repository around them. A link that walks out of the package directory has nothing to walk to there.

`bela/README.md` knows this and says so, at its `docs/fft.md` link:

> Both links are absolute because this file is read on crates.io, where the repository around it is not there.

Neither file follows it. Counted on `docs/scope-inventory` (`grep -n '](\.\./' bela/README.md bela-sys/README.md`), **fourteen links leave a package directory**: nine in `bela-sys/README.md` — `docs/fft.md`, `docs/board-facts.md`, `docs/midi.md`, `docs/scope.md`, `bela/README.md`, and `docs/cross-compile.md` four times — and five in `bela/README.md`, the file that states the rule: `bela-sys`, `docs/multithreaded-rendering.md`, the repository `README.md`, and `docs/cross-compile.md` twice.

Nothing here is broken in the repository — every one resolves on GitHub. It is only the published rendering that loses them, which is why it has gone unnoticed.

## Why this is not a "make them all absolute" one-liner

An absolute link pins a branch. `https://github.com/akiomik/bela-rs/blob/main/...` follows `main`, so a crates.io page for 0.8.1 sends its reader to whatever the file says now. That is fine for `cross-compile.md`, which describes a procedure, and less fine for anything describing what a version has. The two absolute links already in `bela/README.md` accept that trade; a sweep should decide it deliberately rather than inherit it fourteen more times.

The alternative is to stop linking out of the package and name the path in prose, which is what `bela`'s rustdoc does with `docs/`: 43 of its 44 mentions are prose and exactly one is a link. That reads worse in a README and never dangles.

A third answer is to package the files — `include = [...]` in each `Cargo.toml` — which would make the relative links correct where they are read. That has its own cost: `docs/` is 3400 lines and would ship with both crates.

Any of the three is fine. What is not fine is the current state, where the rule is written down in one file and followed in neither.

Found while reviewing #157, which added a fifteenth such link, made it absolute, and then took the absolute form back out rather than widen a documentation pull request into this.

Guida per i contributori

Apri la guida per i contributori

Direzione di ricerca

Read bela-sys/Cargo.toml, bela/Cargo.toml, and both package READMEs to understand how crates.io renders them. Run grep -n '](\.\./' bela/README.md bela-sys/README.md from docs/scope-inventory, then compare the three resolution approaches described in the issue before confirming the preferred direction. Done means the published README links no longer dangle and the stated linking rule is followed.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
rust
Ambito
documentation
Tipo di issue
Documentazione
Difficoltà
3/5
Tempo stimato
1-2 giorni
Stato di attività
Attiva
Chiarezza
Abbastanza chiara
Idoneità per principianti
45/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.