Docs are out of date

[GuillaumeGomez]

• The rustdoc-comments repo needs to have complete (not perfect) API documentation.
• There needs to be a script or a build script feature to insert that documentation into the source code.

[Anachron]

Please put this back on rust-ci.org and update the docs ... 👍

[GuillaumeGomez]

The export on rust-ci docs is working again ?

[Anachron]

@GuillaumeGomez where is the issue? On Rust-Gnome or rust-ci-side?

For now I downloaded the old docs via

wget -r -k -np http://rust-ci.org/jeremyletang/rgtk/doc/rgtk/

But I really want to be up to date (learning Rust and GTK).

[GuillaumeGomez]

It is on rust-ci. If you want the doc of gtk, just donwload the sources and then:

> cargo doc

It'll be up to date and you won't need an internet access to read it. ;)

[Anachron]

@GuillaumeGomez thanks for the info, can you link me to the build?

I will do the building myself then, I already loaded the source =)
Thanks for this project, it actually made me want to learn Rust as I'm a big fan of GTK.

[GuillaumeGomez]

Well, you can download a zip of gtk sources here. However, I'm not sure gtk build with a beta version of rustc, you'll need the nightly (available on the rust website).

To build gtk, just do:

> cargo buid

[Anachron]

Oh I mean I will build the docs myself then =) The other build from src is already very well explained in your README.md.
I was searching on rust-ci.org but I could not find the build for rust-gnome/gtk, did I mis something?

[GuillaumeGomez]

It's not on rust-ci. I'll put rust-gnome on crates.io very soon. You should prefer it over rust-ci.

[SirVer]

Are there even docs anymore? I was trying to build the docs locally using cargo doc, but it never runs through:

cargo doc --features gtk_3_14 --verbose                                       /tmp/gtk
       Fresh gcc v0.3.11
       Fresh pkg-config v0.3.5
       Fresh c_vec v1.0.12
       Fresh bitflags v0.1.1
       Fresh libc v0.1.8
       Fresh glib-sys v0.1.2 (https://github.com/rust-gnome/glib#ccbc2696)
   Compiling cairo-rs v0.0.4 (https://github.com/rust-gnome/cairo#2c95d05c)
     Running `rustdoc /Users/sirver/.multirust/toolchains/nightly/cargo/git/checkouts/cairo-571ad16295201b7a/master/src/lib.rs --crate-name cairo -o /private/tmp/gtk/target/doc -L dependency=/private/tmp/gtk/target/debug/deps -L dependency=/private/tmp/gtk/target/debug/deps --extern c_vec=/private/tmp/gtk/target/debug/deps/libc_vec-944f3e3f45efffaf.dylib --extern c_vec=/private/tmp/gtk/target/debug/deps/libc_vec-944f3e3f45efffaf.rlib --extern c_vec=/private/tmp/gtk/target/debug/deps/libc_vec-944f3e3f45efffaf.dylib --extern c_vec=/private/tmp/gtk/target/debug/deps/libc_vec-944f3e3f45efffaf.rlib --extern glib=/private/tmp/gtk/target/debug/deps/libglib-06dda2a99b4e937f.rlib --extern glib=/private/tmp/gtk/target/debug/deps/libglib-06dda2a99b4e937f.rlib --extern libc=/private/tmp/gtk/target/debug/deps/liblibc-ef5cbad4ef5c7a1e.rlib --extern libc=/private/tmp/gtk/target/debug/deps/liblibc-ef5cbad4ef5c7a1e.rlib --extern cairo_sys=/private/tmp/gtk/target/debug/deps/libcairo_sys-ce4b015e84866ded.rlib --extern cairo_sys=/private/tmp/gtk/target/debug/deps/libcairo_sys-ce4b015e84866ded.rlib`
       Fresh cairo-sys-rs v0.1.3 (https://github.com/rust-gnome/cairo#2c95d05c)
       Fresh pango-sys v0.1.2 (https://github.com/rust-gnome/pango#80e4bbec)
       Fresh glib v0.0.3 (https://github.com/rust-gnome/glib#ccbc2696)
       Fresh gdk-sys v0.1.1 (https://github.com/rust-gnome/gdk#9bdca522)
       Fresh pango v0.0.3 (https://github.com/rust-gnome/pango#80e4bbec)
       Fresh gtk-sys v0.1.3 (file:///private/tmp/gtk)
Could not document `cairo-rs`.

Caused by:
  Process didn't exit successfully: `rustdoc /Users/sirver/.multirust/toolchains/nightly/cargo/git/checkouts/cairo-571ad16295201b7a/master/src/lib.rs --crate-name cairo -o /private/tmp/gtk/target/doc -L dependency=/private/tmp/gtk/target/debug/deps -L dependency=/private/tmp/gtk/target/debug/deps --extern c_vec=/private/tmp/gtk/target/debug/deps/libc_vec-944f3e3f45efffaf.dylib --extern c_vec=/private/tmp/gtk/target/debug/deps/libc_vec-944f3e3f45efffaf.rlib --extern c_vec=/private/tmp/gtk/target/debug/deps/libc_vec-944f3e3f45efffaf.dylib --extern c_vec=/private/tmp/gtk/target/debug/deps/libc_vec-944f3e3f45efffaf.rlib --extern glib=/private/tmp/gtk/target/debug/deps/libglib-06dda2a99b4e937f.rlib --extern glib=/private/tmp/gtk/target/debug/deps/libglib-06dda2a99b4e937f.rlib --extern libc=/private/tmp/gtk/target/debug/deps/liblibc-ef5cbad4ef5c7a1e.rlib --extern libc=/private/tmp/gtk/target/debug/deps/liblibc-ef5cbad4ef5c7a1e.rlib --extern cairo_sys=/private/tmp/gtk/target/debug/deps/libcairo_sys-ce4b015e84866ded.rlib --extern cairo_sys=/private/tmp/gtk/target/debug/deps/libcairo_sys-ce4b015e84866ded.rlib` (exit code: 101)
--- stderr
/Users/sirver/.multirust/toolchains/nightly/cargo/git/checkouts/cairo-571ad16295201b7a/master/src/patterns.rs:33:5: 42:6 error: non-exhaustive patterns: `Mesh` not covered [E0004]
/Users/sirver/.multirust/toolchains/nightly/cargo/git/checkouts/cairo-571ad16295201b7a/master/src/patterns.rs:33     match pattern_type {
/Users/sirver/.multirust/toolchains/nightly/cargo/git/checkouts/cairo-571ad16295201b7a/master/src/patterns.rs:34         PatternType::Solid            => Box::new(SolidPattern::wrap(ptr))   as Box<Pattern>,
/Users/sirver/.multirust/toolchains/nightly/cargo/git/checkouts/cairo-571ad16295201b7a/master/src/patterns.rs:35         PatternType::Surface          => Box::new(SurfacePattern::wrap(ptr)) as Box<Pattern>,
/Users/sirver/.multirust/toolchains/nightly/cargo/git/checkouts/cairo-571ad16295201b7a/master/src/patterns.rs:36         PatternType::LinearGradient   => Box::new(LinearGradient::wrap(ptr)) as Box<Pattern>,
/Users/sirver/.multirust/toolchains/nightly/cargo/git/checkouts/cairo-571ad16295201b7a/master/src/patterns.rs:37         PatternType::RadialGradient   => Box::new(RadialGradient::wrap(ptr)) as Box<Pattern>,
/Users/sirver/.multirust/toolchains/nightly/cargo/git/checkouts/cairo-571ad16295201b7a/master/src/patterns.rs:38         #[cfg(cairo_1_12)]
                                                                                                                 ...
error: aborting due to previous error

[GuillaumeGomez]

@SirVer: I discovered travis-cargo today. I'll try to add it on my personal repositories first before adding it on rust-gnome's. However, it doesn't solve this issue. What do you think about it @gkoz ?

[gkoz]

Looks like it could work but since travis has a pretty old set of libraries, a lot of stuff will be missing. And I don't think any progress has been made on gtk-rs/gdk#49, so the utility of rustdoc is further limited by that.

[Anachron]

@gkoz I'm new here, so please excuse my stupid question...
What does gdk have to do with travis failing to build docs for rust-gnome (gtk)?

[GuillaumeGomez]

About rust-gnome/gdk#49, we can still generate a documentation. Little is better than nothing I guess ? Have you taken a look at travis-cargo ? It could be interesting.

[gkoz]

@Anachron we'd obviously want to document all crates, not only gtk. And gtk will in time face the problems described in that issue too. I mean, you're not going to like that documentation.

@GuillaumeGomez I've looked at it briefly and it seems similar to the former approach that had been used in rgtk. Right now I have my hands full with developing a multi-threaded cairo example, hacking on gir and preparing to migrate to the generated sys crates.

[GuillaumeGomez]

@gkoz: Ok, I'll take a look at it on some personal repositories of mine. The goal of it is to directly push on a github wiki, which is a big lack on rust-gnome's repositories.

[gkoz]

I'm making this a tracking issue for some rustdoc-stripper integration.

[gkoz]

I think I've figured out a way to solve the integration issue.

• Publish the docs repo as a crate that just exposes the cmts files contents, e.g.

  pub const GTK_DOCS: &'static str = include_str!("gtk.cmts");
  

  This crate is going to be licensed under LGPL but none of it will ever end up in the application binary.

• Publish the library part of rustdoc_stripper.

• A crate build script adds them as build-dependencies and implements the following features:

  • insert the docs from the docs package,
  • strip the docs,
  • check if any unstripped docs are present (to prevent them from sneaking into pull requests).

This way cargo handles the versions and downloads for us and the docs can be updated more frequently than the code if necessary.

[GuillaumeGomez]

@gkoz: What library part of rustdoc_stripper are you talking about? The public interfaces are already available (and used in gir). So I don't see what you're referring to.

[gkoz]

The implementation.