lgpl-docs

LGPL-licensed docs for Gtk-rs crates.

Structure

The docs for each library come from two files:

docs.rs is maintained manually, its entries take precedence over the vendor.rs file. PRs should normally target this file.
vendor.rs is generated by gir via simple transformation of the upstream docs found in GIR definitions. It serves as a fallback, the docs in it are tailored for C not Rust. This file should not be hand-edited.

You can generate it as follows:

cd gir
cargo run --release -- -c ../your-repo/Gir.toml -d ../gir-files/ -o ../your-repo/ -m doc

Cairo, which lacks GIR definitions, doesn't have a vendor.rs file.

Format

The format of the files is Markdown with extra metadata in HTML-like comments, which ties each entry to a specific Rust item. For example, this rustdoc snippet:

impl Button {
    /// Creates a new `Button` widget. To add a child widget to the button,
    /// use `Container::add`.
    ///
    /// # Returns
    ///
    /// The newly created `Button` widget.
    pub fn new() -> Button {

corresponds to this entry in gtk/vendor.md:

<!-- impl Button::fn new -->
Creates a new `Button` widget. To add a child widget to the button,
use `Container::add`.

# Returns

The newly created `Button` widget.