docs.rs only shows empty crates

[jonas-schievink]

For example: https://docs.rs/stm32f4/0.1.0/stm32f4/

The features added in https://github.com/onur/docs.rs/pull/73 can be used to make docs.rs build the crates with all features enabled:

[package.metadata.docs.rs]
all-features = true

[jonas-schievink]

Actually, scratch that. cargo doc --open --all-features takes 10 minutes and uses up to 12 GB of memory, so I doubt the docs.rs builder would like that. I'd still like to find some solution for hosted docs, though.

[adamgreig]

I was trying to look for that feature to make docs.rs build all features and couldn't find it anywhere, so thanks! But I fear you're right and it won't enjoy the intense RAM usage.

At the moment I have a sort of halfway towards being docs thing at https://stm32.agg.io/rs but it's not really what you want. I think I might be able to build them locally and host somewhere, but it would be nice if they could be on docs.rs. Could always add a link in the crate READMEs though.

[adamgreig]

I uploaded docs for just stm32f405 here to try it out, but it takes a lot of time to generate and upload and about 500MB per device. I think I can probably wrangle that for everything but it'l take a while and is a bit extreme. I'll look in to generating them on the server at least.

[gbip]

Maybe you could (ab)use Travis CI to generate the doc ?

[jonas-schievink]

Travis only provides like 2 GB of RAM

[gbip]

Generating the doc for 1 micro-controller took roughly 1.5 Gb of Ram on my computer, so I guess it is still doable, don't you think ?

[jonas-schievink]

Then you'd have to generate multiple documentation pages per crate since it's necessary to document all microcontrollers, which makes navigating the docs annoying and still doesn't make them show up on docs.rs

To solve this issue properly at least one of these thing probably needs to happen:

• Improve rustdoc's performance and memory use significantly
• Improve the code generated by svd2rust (primarily by generating less of it)
• We just use single-microcontroller crates instead

[phil-opp]

Maybe a dumb question, but: Have you actually tried to generate the docs on docs.rs? Or do you just think that the docs.rs builder is not capable enough? Because normal svd2rust crates like stm32f7x6 seem to work fine on docs.rs. (I know that this crate is different because it contains code for multiple different devices, but I think it's worth a try.)

[adamgreig]

I haven't actually tried. We'd just need to set

[package.metadata.docs.rs]
all-features = true

in the Cargo.toml of one crate and see what happens. I'm planning on a 0.2.1 release either today or tomorrow so I'll set that on one crate and see what it does.

[phil-opp]

Thanks!

[adamgreig]

I added that to stm321, stm32f2, stm32f3 crates before releasing 0.2.1.

However, the cortex-m dependency fails to build docs at the moment, so that might trip up docs.rs irregardless.

[adamgreig]

Mixed results: stm32f1 worked, stm32f2 did too, but stm32f3 got this error log indicating the process was SIGKILL'd.

I'm guessing the first two just about fit but the f3 didn't, which doesn't bode well for f4/f7 which are bigger, but maybe f0 would work.

[phil-opp]

Thanks for testing! I think we should open an issue in the docs.rs repo for this, maybe there is a way to increase limits. For the meantime we could enable only a few device features instead of all features so that there's at least some kind of documentation.