In life, there's no need to reinvent the wheel. This is true for Rust and programming too. We can leverage other people's code in ours, in order to build even more useful software for our domain. Just for context, imagine as a chef you had to create your own sauce, spice, and everything nice everytime you make a meal. It would take you forever to make a simple meal, whereas you can just buy all those ingredients, mix them up to make your own special, secret recipe 🥘. N.B This blog post isn't so much about the code, but about publishing code for the world to use.

Publishing our rust crate

Let's build a basic stats crate to help perform basic calculations such as finding;

• the mean
• variance
• standard deviation To see the project on Github, click here. Link to the published crate on crates.io Running it in the command line and calling all the functions, we can see the output below.

What is crates.io?

Crates.io is where Rust developers share and download crates (packages). If you are coming from other programming languages you might similar repositories;

• Javascript NPM
• Python pip

Documenting our package

Having good documentation helps other software developers know how to use our code. Luckily, Rust makes this very easy by simply adding comments to our code. Normal comments we've previously used have 2 forward slashes like //. Now for documentation, we use 3 ///. So let's document a function we have called mean in our easy_stats crate.

/// Calculate the mean from a list of numbers
///
/// # Examples
///
/// ```
/// let arg = vec![1.0,2.0,3.0,4.0, 5.0];
/// let average = easy_stats::mean(&arg);
///
/// assert_eq!(3.0, average);
/// ```

We firstly describe what the function does and then give an example of how to use it in your code.

Commenting the root

Since this is a crate, with a bunch of related functionality. We can also document the entire package at the very top. Notice that we use //! instead of ///.

//! # Rust Stats
//!
//! `stats` is a collection of utility functions which make
//! performing descriptive statistics easy

Generate an html (web) page

Rust makes it easy to have good looking documentation, by allowing us to generate an HTML (web) page of our documentation by running a simple command.

cargo doc --open

The output looks like; When we navigate to the mean function, users can get more detailed information on how to use it.

Documentation tests

This is by far the most mind-blowing part of the documentation. We can test the code snippets inside our documentation. Please have a look at my day 11 post on Testing here.

Running cargo test, there is a section called doc tests which looks like this;

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
 
  Doc-tests easy_stats
 
running 3 tests
test src/lib.rs - mean (line 11) ... ok
test src/lib.rs - variance (line 44) ... ok
test src/lib.rs - std (line 29) ... ok
 
test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 1.15s

Whenever we change our functions code in this crate called easy_stats, if the changes are breaking the assert_eq test will fail signaling that the code and our documentation are misaligned.

Creating a Crates.io Account

In order to share our crate with others on crates.io, we need to have an account. The only way to create an account is by linking it to your Github profile. Secondly, navigate to your profile section and generate an API key, which you shouldn't share with anyone. Thereafter run cargo login <API-KEY>

cargo login abcdefghijklmnopqrstuvwxyz012345

Add metadata

Once we are set up with our account and are ready to publish, we need to add some meta-deta to our Cargo.toml file.

[package]
name = "easy_stats"
version = "0.1.0"
edition = "2021"
description = "A simple rust package to perform basic descriptive stats on a data set."
license = "MIT OR Apache-2.0"

Run ;

cargo publish

The output will look like;

masai@Masais-Air stats % cargo publish
  Updating crates.io index
warning: manifest has no documentation, homepage or repository.
See https://doc.rust-lang.org/cargo/reference/manifest.html#package-metadata for more info.
 Packaging easy_stats v0.1.0 (/Users/masai/programming/rust/stats)
 Verifying easy_stats v0.1.0 (/Users/masai/programming/rust/stats)
 Compiling easy_stats v0.1.0 (/Users/masai/programming/rust/stats/target/package/easy_stats-0.1.0)
  Finished dev [unoptimized + debuginfo] target(s) in 1.87s
 Uploading easy_stats v0.1.0 (/Users/masai/programming/rust/stats)

Conclusion

For the first time in my life, I created a package for other software developers around the world to use 🕺🏼. This is definitely not much, but it is the beginning of many more to come. If you are a Rust developer, please use my package with the link here or better yet, please contribute to it to make it better for the entire Rust community. Thanks for spending some time learning Rust with me. Until next time. Peace ✌🏼 .