stm32-rs

stm32-rs copied to clipboard

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

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.

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.

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.

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

Travis only provides like 2 GB of RAM

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 ?

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

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.)

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.

Thanks!

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.

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.

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.

That's not a bad idea... perhaps pick one or two representative devices per family which are likely to be popular or similar to everything else.

I've updated crates to all build at least one or two devices. We'll see if it works and if any fail I might need to reduce the number of devices they try to build even further. I'll leave this issue open for now as it's still not an entirely satisfactory solution...

Awesome, thanks @adamgreig!

Might I suggest changing the device choices to reflect availability of dev boards? For instance, in the stm32l4 series, the two main Nucleos are NUCLEO-L476RG and NUCLEO-L432KC, so it would make sense to build stm32l4x2 and stm32l4x6 instead of the current 4x1 and 4x5.

I believe this issue has been resolved as of the 0.6.0 release.

We still don't build all devices in the docs -- each family crate has a list of which devices to include which is meant to be a vaguely representative subset, but I think docs.rs will still fail to build the entire f4 crate for example.

Gotcha, just checked a handful of random device crates so I guess I got unlucky, disregard :p

Improve rustdoc's performance and memory use significantly

If someone can give a flamegraph or perf mem record, I'd be interested in improving rustdoc's performance. Or you could measure it some other way, the main ones I know about are -Z self-profile and -Z time-passes.