docs.rs build failing

[hannobraun]

Didn't we just fix that? Anyway, it's failing: https://docs.rs/crate/lpc8xx-hal/0.9.0/builds/355015

[snakehand]

Building doc failed for me - seems I need to specify a target for it to build, which begs the question: Shouldn't there be 2 versions of the docs build ( 824 / 845 ) since the APIs are slightly different. Does docs.rs even handle that ? Maybe one wayt to fix it is to have 2 meta crates ( lpc824-hal and lpc845-hal ) that that has lpc8xx-hal as a dependency with the approriate target config ? Sounds hackish to me, but I can't think of anything else.

[hannobraun]

Hi @snakehand, thank you for your comment. The doc situation certainly isn't ideal, but I don't think additional crates are the answer. We used to do exactly what you proposed, and that caused problems with duplicated code (something about traits that couldn't be implemented unless they were local; I don't recall the details) and was more maintenance work overall (more crates means more work releasing them, for example). There might have been other problems I don't recall.

I've been thinking for a while that using mutually exclusive Cargo features to specify the target is far from ideal (although that's how most HALs are doing it). I think it must be possible to structure things in a way, that the code for multiple targets can exist side by side. We'd still have Cargo features for each target, so users can compile only what they need, but then we could just enable all targets for the docs, so the API reference would cover the full API.

But that's just an idea. I haven't had a chance to experiment with this, and even if everything worked out as I imagine, this would be a non-trivial amount of work. I won't have the capacity to do this any time soon, maybe ever. I think for now, your best bet is to build local documentation for the target you need and just use that.