search

rust-lang / docs.rs

crates.io documentation generator
https://docs.rs
MIT License
990 stars 198 forks source link

API for publishing documentation #93

Open chris-zen opened 7 years ago

chris-zen commented 7 years ago

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 commented 7 years ago

I just found this related issue at crates.io which is exactly what I was proposing here. https://github.com/rust-lang/crates.io/issues/91

johalun commented 7 years ago

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

Kixiron commented 4 years ago

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

jyn514 commented 4 years ago

@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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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