Support intralinks to other item types

[orium]

Currently not all item types can be used in intralinks:

• [x] Support intralinks to types methods, consts, and types defined in impl blocks. (issue #166) ** There's a limitation on the place where the impl block is defined (issue #170).
• [ ] Support intralinks to struct and union fields.
• [ ] Support intralinks to enum variants.
• [ ] Support intralinks to trait items.

[RReverser]

Supporting trait items would be very useful indeed, as it would complete coverage for all top-level items.

[orium]

You can links to traits, you just can't link to things inside traits, such as methods or associated types.

[RReverser]

You can links to traits, you just can't link to things inside traits, such as methods or associated types.

Hm that's not what I'm seeing, links to traits don't seem to work either and I'm getting warnings that they're not resolved.

[RReverser]

Just tried again and it's definitely not resolving my traits:

warning: Could not resolve definition of `crate::api::Focuser`.
warning: Could not resolve definition of `crate::api::ObservingConditions`.
warning: Could not resolve definition of `crate::api::Rotator`.
...

By the way, have you considered using rustdoc's API instead of resolving things manually? @LukeMathWalker did a great talk on it recently, but TLDR is that you can consume data already preprocessed by rustdoc via their JSON format, e.g. via https://crates.io/crates/rustdoc_json.

[orium]

Just tried again and it's definitely not resolving my traits

Can you point me to your project or give me a minimal example? I can't reproduce it:

$ cat -p src/main.rs
//! [Focuser](crate::api::Focuser)

mod api {
    trait Focuser {
    }
}

fn main() {
}
$ cargo rdme --force
$ cat -p README.md
<!-- cargo-rdme start -->

[Focuser](https://docs.rs/foo/latest/foo/api/trait.Focuser.html)

<!-- cargo-rdme end -->

There's limitation like symbol re-export not working (#5).

have you considered using rustdoc's API instead of resolving things manually?

Have to check that, but if it involves having rust nightly installed (and I'm guessing it does to access the compiler's api) I don't want to use it: I don't want users to have to install anything for cargo-rdme to work.

[RReverser]

There's limitation like symbol re-export not working (#5).

Ah maybe that's it, I'll recheck.

Have to check that, but if it involves having rust nightly installed (and I'm guessing it does to access the compiler's api) I don't want to use it: I don't want users to have to install anything for cargo-rdme to work.

I think it does for now but if it will support arbitrary rustdoc out of the box it seems worth it - it's easier to install nightly toolchain and do cargo +nightly install cargo-rdme than it is to rewrite docs just to account for cargo-rdme's limitations.

[RReverser]

it's easier to install nightly toolchain and do cargo +nightly install cargo-rdme than it is to rewrite docs just to account for cargo-rdme's limitations

Besides, you could probably even link it statically with the rustdoc crate and ship binaries on Cargo releases so users wouldn't have to build / install anything at all. Although that seems a more unstable route than relying on JSON output from the actual binary.

[RReverser]

I should probably also link to https://rust-lang.github.io/rfcs/2963-rustdoc-json.html which has a fairly detailed documentation of the format.

[RReverser]

There's limitation like symbol re-export not working (#5).

Ah I missed log at the top:

warning: Unable to find module file for module crate::api in directory "..."

I think the problem is that I'm using module with custom path via #[path = "..."] mod api; attribute.

[orium]

By the way, have you considered using rustdoc's API instead of resolving things manually? @LukeMathWalker did a great talk on it recently, but TLDR is that you can consume data already preprocessed by rustdoc via their JSON format, e.g. via crates.io/crates/rustdoc_json.

I decided to give it a go (#177). I'm implementing this in branch https://github.com/orium/cargo-rdme/tree/rustdoc-json. Very preliminary work, but it already passes 44 integration tests (and fail 7).