Broken documentation

[spacekookie]

Hey there, trying to read the docs at https://docs.rs/crate/magick_rust/0.7.0 results in a weird error message that I didn't know existed:

docs.rs failed to build magick_rust-0.7.0
Please check build logs and if you believe this is docs.rs' fault, report into this issue report.

It seems not to be able to build at all because of not finding imagemagick 7. Some way you can get around that to make the docs work again?

[nlfiedler]

I did not know that even existed, and I have no idea how one would configure a crate to work correctly with docs.rs. If I had to guess, I'd say this is a special case that is not supported by their platform. This crate is especially difficult because of the external dependencies and automated binding generation.

[QuestofIranon]

Came here to report this too, but for reference to anyone finding this issue, you can also generate the docs locally and it works fine as long as you have imagemagick installed.

cargo doc --open

[nlfiedler]

I'm a bit slow, but it occurred to me that a way to address this is to build the docs locally and push to github.io. Getting this crate to build for docs.rs is basically out of the question, so building and publishing manually is likely the best option. I'll look into this soon.

[rminderhoud]

I've created a docs sample for 0.13.0 at https://rminderhoud.github.io/magick-rust/0.13.0/magick_rust/.

Repo: https://github.com/rminderhoud/magick-rust/tree/gh-pages

Steps:

• git checkout --orphan gh-pages
• git rm -rf .
• cargo doc
• Add .gitignore
• cp target/doc ./0.13.0

Currently can't create a pull request because the histories are unrelated so there's no branch to merge into. Happy to open a pull request if an empty gh-pages branch is created, otherwise it's pretty straightforward to reproduce.

[nlfiedler]

@rminderhoud Thanks for the guidance. I realize I suggested committing the docs to the repository, but that commits 58MB of build artifacts to the repository history forever, and that grows with each new build of the docs. Another approach occurred to me, which is to create an "imagemagick-sys" crate and add that as a dependency to magick-rust. In theory, that should make it possible for docs.rs to build the documentation (it does for rust-rocksdb so it must be possible).

[rminderhoud]

@nlfiedler I agree that the above solution is not ideal. It might be slightly better mitigated with LFS but github doesn't allow you to use LFS on public forks so I was forced to commit the binaries directly.

I think there would still be issues building it on docs.rs unless you went down the "bundled" route. The SDL2 crate has the option to use the bundled version of SDL2 or to link to your own. It looks like rust-rocksdb does the same except doesn't bundle binaries but has submodules of the rocksdb source and compiles it as part of the low-level sys crate.

[nlfiedler]

Here are the generated docs: http://nlfiedler.github.io/magick-rust/magick_rust/index.html

Now just need to fill in the many blanks.