API for publishing documentation

[chris-zen]

Currently, docs.rs is generating the documentation from crates.io which is very convenient, but there is a limitation to that, the project has to be compilable in a linux machine, which is not the case for all the libraries related to Windows or Mac OSX. There is a lot of effort ongoing in Rust to be a truly portable language across different operating systems, and it is an important limitation that a great service such as docs.rs for hosting documentation is not able to work with those non linux systems.

An idea to alleviate this limitation, would be to provide an API to publish the documentation that has been already generated by the authors of the libraries (using cargo doc in their non linux machine). Then it would be possible to add an extension to cargo to make the publishing as easy as it is to publish a release into crates.io. And why not, the already existing cargo publish could do the job of publishing the library into crates.io and the docs into docs.rs.

How does it sound ? Is it very difficult to achieve ?

[chris-zen]

I just found this related issue at crates.io which is exactly what I was proposing here.
rust-lang/crates.io#91

[johalun]

+1 for this. I just published a FreeBSD-only crate and realized I couldn't get any docs on docs.rs :(

[Kixiron]

Docs.rs now supports building across multiple targets which include Windows, OSX and Linux

[jyn514]

@Kixiron this is not true. We always build on a host of linux, so if the crate has native dependencies only available on other platforms, the build will fail. We allow passing --target, which is not really related to this issue.

[jyn514]

How does it sound ? Is it very difficult to achieve ?

The issue I would be concerned about is making sure that the documentation is not malicious/doesn't have javascript/etc. Ideally we'd have a way to verify that the documentation uploaded is the same as we would generate if we had a MacOS/FreeBSD/Windows host. Otherwise, it's easy to make mistakes where the documentation published isn't reproducible because it depends on something you had installed locally. Ideas about this are welcome!

[Kixiron]

Unfortunately due to how docker works, the most flexible host OS is Windows, which can run both Windows and Linux containers (but not at the same time which is fun) while every other host can just run its own platform. It's conceivable that if we decoupled the builder from the webserver we could run multiple independent builders (one windows, one linux, one mac) that all do their own target's documentation, but that would require 2-3 times the server costs (maybe more because some targets are more expensive)

[jyn514]

To be clear, I am not suggesting that docs.rs suddenly gain a (possibly unbounded) number of new hosts to build documentation on. I'm asking for ideas on how to make sure that uploaded docs are reproducible.

[Kixiron]

Yes, I was just giving the pros/cons of attempting to natively build most/every/whitelisted targets