search

deadlinks / cargo-deadlinks

Cargo subcommand for checking your documentation for broken links
Apache License 2.0
149 stars 16 forks source link

Allow ignoring specific broken links #133

Open jyn514 opened 3 years ago

jyn514 commented 3 years ago

This is needed to replace src/tools/linkchecker in the rust-lang repo (https://github.com/deadlinks/cargo-deadlinks/issues/105). These are the currently ignored links: https://github.com/rust-lang/rust/blob/e4297ba39ce07a0b0000841b50154ea53783a024/src/tools/linkchecker/main.rs#L31-L91

So we need a way to ignore:

  1. Broken fragments
  2. Intra-doc like links ([<code></code>])
  3. and for both of those, ignore all links within a given file (https://github.com/rust-lang/rust/blob/e4297ba39ce07a0b0000841b50154ea53783a024/src/tools/linkchecker/main.rs#L60-L61)

I'm imagining a setup like this in deadlinks.toml:

[fragments]
"std/io/struct.IoSlice.html" = [
    "#method.as_mut_ptr",
    "#method.sort_by_key",
    "#method.make_ascii_uppercase",
    "#method.make_ascii_lowercase",
    "#method.get_unchecked_mut",
]

[intra_doc_links]
"reference/print.html" = all
"reference/comments.html" = [
     "/</code> <code>!",
     "*</code> <code>!",
]

The reason I don't want to put it in Cargo.toml is that allows it to be used with deadlinks and not just cargo-deadlinks.

As an extension, this could allow ignoring completely missing files, but that wouldn't be necessary for replacing linkchecker. I think it's a useful feature separate from rust-lang/rust, though.

jyn514 commented 3 years ago

These are the current broken links for the rust-lang/rust repo (after running a full x.py doc):

Found invalid urls in std/collections/btree_set/struct.BTreeSet.html:
    Fragment #insert-and-complex-keys at std/collections/btree_set/index.html does not exist!
Found invalid urls in std/collections/btree_map/struct.BTreeMap.html:
    Fragment #insert-and-complex-keys at std/collections/btree_map/index.html does not exist!
Found invalid urls in std/io/struct.IoSlice.html:
    Fragment #method.sort_by_key at std/io/struct.IoSlice.html does not exist!
    Fragment #method.as_mut_ptr at std/io/struct.IoSlice.html does not exist!
Found invalid urls in std/primitive.slice.html:
    Linked file at path /home/joshua/rustc3/build/x86_64-unknown-linux-gnu/std/primitive.slice.html does not exist!
    Linked file at path /home/joshua/rustc3/build/x86_64-unknown-linux-gnu/std/primitive.slice.html does not exist!
Found invalid urls in rust-by-example/print.html:
    Fragment #%E2%80%A0 at rust-by-example/print.html does not exist!
Found invalid urls in rust-by-example/error/result/enter_question_mark.html:
    Fragment #%E2%80%A0 at rust-by-example/error/result/enter_question_mark.html does not exist!
Found invalid urls in reference/types/tuple.html:
    Fragment #2 at reference/types/tuple.html does not exist!
Found invalid urls in reference/print.html:
    Fragment #2 at reference/print.html does not exist!
Found invalid urls in alloc/collections/btree_set/struct.BTreeSet.html:
    Fragment #insert-and-complex-keys at alloc/collections/btree_set/index.html does not exist!
Found invalid urls in alloc/collections/btree_map/struct.BTreeMap.html:
    Fragment #insert-and-complex-keys at alloc/collections/btree_map/index.html does not exist!
Found invalid urls in cargo/reference/build-script-examples.html:
    Fragment #%E2%80%A0 at cargo/reference/build-script-examples.html does not exist!
Found invalid urls in cargo/print.html:
    Fragment #%E2%80%A0 at cargo/print.html does not exist!

Of those, these seem like bugs in deadlinks itself:

Found invalid urls in rust-by-example/error/result/enter_question_mark.html:
    Fragment #%E2%80%A0 at rust-by-example/error/result/enter_question_mark.html does not exist!
Found invalid urls in reference/types/tuple.html:
    Fragment #2 at reference/types/tuple.html does not exist!

and this I'm not sure about:

Found invalid urls in std/primitive.slice.html:
    Linked file at path /home/joshua/rustc3/build/x86_64-unknown-linux-gnu/std/primitive.slice.html does not exist!

/home/joshua/rustc3/build/x86_64-unknown-linux-gnu/doc/std/primitive.slice.html does exist so maybe someone used too many ../?

jyn514 commented 3 years ago

After fixing bugs in both deadlinks and rust-lang/rust, these are the remaining broken links:

> deadlinks build/x86_64-unknown-linux-gnu/doc/
Found invalid urls in std/collections/btree_set/struct.BTreeSet.html:
    Fragment #insert-and-complex-keys at std/collections/btree_set/index.html does not exist!
Found invalid urls in std/collections/btree_map/struct.BTreeMap.html:
    Fragment #insert-and-complex-keys at std/collections/btree_map/index.html does not exist!
Found invalid urls in std/io/struct.IoSlice.html:
    Fragment #method.as_mut_ptr at std/io/struct.IoSlice.html does not exist!
    Fragment #method.sort_by_key at std/io/struct.IoSlice.html does not exist!
Found invalid urls in std/primitive.slice.html:
    Linked file at path /home/joshua/rustc/build/x86_64-unknown-linux-gnu/std/primitive.slice.html does not exist!
    Linked file at path /home/joshua/rustc/build/x86_64-unknown-linux-gnu/std/primitive.slice.html does not exist!
Found invalid urls in alloc/collections/btree_set/struct.BTreeSet.html:
    Fragment #insert-and-complex-keys at alloc/collections/btree_set/index.html does not exist!
Found invalid urls in alloc/collections/btree_map/struct.BTreeMap.html:
    Fragment #insert-and-complex-keys at alloc/collections/btree_map/index.html does not exist!

The link to slice looks related to https://github.com/deadlinks/cargo-deadlinks/issues/37, maybe? See also https://github.com/rust-lang/rust/issues/80175.