Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Initial work on improving the book. #1338

Closed
wants to merge 3 commits into from
Closed

Conversation

ryankopf
Copy link
Contributor

The book is in need of serious work and completion, as this crate is relatively new. Some work in building the book is a challenge due to an issue with mdbook.

After quite a bit of thinking about how best to approach this, I've found the changes in this PR should prove fruitful for future book updates.

Code should be executable directly.

For beginners, it's important that the code in the book be copy and pastable directly into their editor without changes, to help them have a smooth learning experience. This is already the case with the "Hello World" example, where the code has a main() function and everything.

Some of the later code, however, just looks like script snippets. This is odd in Rust, as Rust is not a scripting language, and these code fragments can not be executed.

I found out these code fragments exist AS fragments because the auto-testing facilities available in mdbook don't support some crates, where you need to specify the location. So the code was instead written in testable ".rs" files and imported into the book.

My PR and suggestion for future book updates - which I am likely to make several of if this is improved - is to make a very couple of simple modifications to the test anchors, splitting it out into a "top" (includes) and content, which allows for a very simple main() structure to be written inside the 'ignored' Rust code that the mdbook program can not execute.

To note, this PR should not be controversial because:

  • Currently the book uses a mix of externally imported code and direct code in the MD files, but testing is inconsistent
  • There is untested code already in the book, on the very second page, and this change will serve as an excellent guide to turning that code into tested code instead. I have not done that in this PR to keep it simple.

@ryankopf
Copy link
Contributor Author

ryankopf commented Nov 17, 2023

I will note this has been tested with cargo test and md book build, and the output looks great, fully runnable code.

use candle::Device;
use hf_hub::api::tokio::Api;

#[tokio::main]
async fn main() {
    let api = Api::new().unwrap();
    let repo = api.model("bert-base-uncased".to_string());

    let weights_filename = repo.get("model.safetensors").await.unwrap();

    let weights = candle::safetensors::load(weights_filename, &Device::Cpu).unwrap();
    for (name, tensor) in weights.iter() {
        println!("Weight: {}, Dimensions: {:?}", name, tensor);
    }
}

@ryankopf ryankopf closed this Jan 24, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant