Overhaul documentation

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 This is a broad overview of the changes that have been made over the lifespan of this library.
 
+## v0.25.1 - 2023-10-05
+
+- Overhaul documentation
+
 ## v0.25.0 - 2023-06-04
 
 - Add Rating, RatingSystem, RatingPeriodSystem, TeamRatingSystem, and MultiTeamRatingSystem traits

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "skillratings"
-version = "0.25.0"
+version = "0.25.1"
 edition = "2021"
 description = "Calculate a player's skill rating using algorithms like Elo, Glicko, Glicko-2, TrueSkill and many more."
 readme = "README.md"

README.md

@@ -27,11 +27,26 @@ Currently supported algorithms:
 Most of these are known from their usage in chess and various other games.  
 Click on the documentation for the modules linked above for more information about the specific rating algorithms, and their advantages and disadvantages.
 
+## Table of Contents
+
+- [Installation](#installation)
+    - [Serde Support](#serde-support)
+- [Usage and Examples](#usage-and-examples)
+    - [Player vs. Player](#player-vs-player)
+    - [Team vs. Team](#team-vs-team)
+    - [Free-For-Alls and Multiple Teams](#free-for-alls-and-multiple-teams)
+    - [Expected Outcome](#expected-outcome)
+    - [Rating Period](#rating-period)
+    - [Switching between different rating systems](#switching-between-different-rating-systems)
+- [Contributing](#contributing)
+- [License](#license)
+
+
 ## Installation
 
 If you are on Rust 1.62 or higher use `cargo add` to install the latest version:
 
-```
+```bash
 cargo add skillratings
 ```
 
@@ -48,7 +63,7 @@ Serde support is gated behind the `serde` feature. You can enable it like so:
 
 Using `cargo add`:
 
-```
+```bash
 cargo add skillratings --features serde
 ```
 
@@ -278,6 +293,50 @@ let new_player = elo_rating_period(&player, &results, &EloConfig::new());
 assert_eq!(new_player.rating.round(), 1362.0);
 ```
 
+### Switching between different rating systems
+
+If you want to switch between different rating systems, for example to compare results or do scientific analyisis, 
+we provide the `Rating`, `RatingSystem` (1v1), `RatingPeriodSystem` (1v1 Tournaments), `TeamRatingSystem` (Team vs. Team) 
+and `MultiTeamRatingSystem` (FFA) traits to make switching as easy as possible.
+
+In the following example, we are using the `RatingSystem` (1v1) Trait with Glicko-2:
+
+```rust
+use skillratings::{
+    glicko2::{Glicko2, Glicko2Config},
+    Outcomes, Rating, RatingSystem,
+};
+
+// Initialise a new player rating with a rating value and uncertainty value.
+// Not every rating system has an uncertainty value, so it may be discarded.
+let player_one = Rating::new(Some(1200.0), Some(120.0));
+// If you want the default values for the rating system, use None instead.
+let player_two = Rating::new(None, None);
+
+// The config needs to be specific to the rating system.
+// When you swap rating systems, make sure to update the config.
+let config = Glicko2Config::new();
+
+// You may also need to use a type annotation here for the compiler.
+let rating_system: Glicko2 = RatingSystem::new(config);
+
+// The outcome of the match is from the perspective of player one.
+let outcome = Outcomes::WIN;
+
+// All rating systems share a `rate` function for performing the actual calculations,
+// plus an `expected_score` function for calculating the expected performances.
+// Some rating systems might have additional functions,
+// which are only available when you use them directly.
+let expected_score = rating_system.expected_score(&player_one, &player_two);
+let (new_one, new_two) = rating_system.rate(&player_one, &player_two, &outcome);
+
+// After that, you can access the players rating and uncertainty with the functions below.
+assert_eq!(new_one.rating().round(), 1241.0);
+// Note that because not every rating system has an uncertainty value,
+// the uncertainty function returns an Option<f64>.
+assert_eq!(new_one.uncertainty().unwrap().round(), 118.0);
+```
+
 ## Contributing
 
 Contributions of any kind are always welcome!  

src/lib.rs

@@ -16,26 +16,42 @@
 
 //! Skillratings provides a collection of well-known (and lesser known) skill rating algorithms, that allow you to assess a player's skill level instantly.  
 //! You can easily calculate skill ratings instantly in 1vs1 matches, Team vs Team matches, or in tournaments / rating periods.  
-//! This library is incredibly lightweight (no dependencies by default), user-friendly, and of course, *blazingly fast*.  
-//!
-//! Currently we support these skill rating systems:  
-//! - **[`Elo`](crate::elo)**
-//! - **[`Glicko`](crate::glicko)**
-//! - **[`Glicko-2`](crate::glicko2)**
-//! - **[`TrueSkill`](crate::trueskill)**
-//! - **[`Weng-Lin`](crate::weng_lin)**
-//! - **[`FIFA Men's World Ranking`](crate::fifa)**
-//! - **[`Sticko`](crate::sticko)**
-//! - **[`Glicko-Boost`](crate::glicko_boost)**
-//! - **[`USCF (US Chess Federation)`](crate::uscf)**
-//! - **[`EGF (European Go Federation)`](crate::egf)**
-//! - **[`DWZ (Deutsche Wertungszahl)`](crate::dwz)**
-//! - **[`Ingo`](crate::ingo)**
+//! This library is incredibly lightweight (no dependencies by default), user-friendly, and of course, *blazingly fast*.
+//!
+//! Currently supported algorithms:
+//!
+//! - [Elo](https://docs.rs/skillratings/latest/skillratings/elo/)
+//! - [Glicko](https://docs.rs/skillratings/latest/skillratings/glicko/)
+//! - [Glicko-2](https://docs.rs/skillratings/latest/skillratings/glicko2/)
+//! - [TrueSkill](https://docs.rs/skillratings/latest/skillratings/trueskill/)
+//! - [Weng-Lin (Bayesian Approximation System)](https://docs.rs/skillratings/latest/skillratings/weng_lin/)
+//! - [FIFA Men's World Ranking](https://docs.rs/skillratings/latest/skillratings/fifa/)
+//! - [Sticko (Stephenson Rating System)](https://docs.rs/skillratings/latest/skillratings/sticko/)
+//! - [Glicko-Boost](https://docs.rs/skillratings/latest/skillratings/glicko_boost/)
+//! - [USCF (US Chess Federation Ratings)](https://docs.rs/skillratings/latest/skillratings/uscf/)
+//! - [EGF (European Go Federation Ratings)](https://docs.rs/skillratings/latest/skillratings/egf/)
+//! - [DWZ (Deutsche Wertungszahl)](https://docs.rs/skillratings/latest/skillratings/dwz/)
+//! - [Ingo](https://docs.rs/skillratings/latest/skillratings/ingo/)
 //!
 //! Most of these are known from their usage in chess and various other games.  
 //! Click on the documentation for the modules linked above for more information about the specific rating algorithms, and their advantages and disadvantages.
 //!
-//! # Installation
+//! ## Table of Contents
+//!
+//! - [Installation](#installation)
+//!     - [Serde Support](#serde-support)
+//! - [Usage and Examples](#usage-and-examples)
+//!     - [Player vs. Player](#player-vs-player)
+//!     - [Team vs. Team](#team-vs-team)
+//!     - [Free-For-Alls and Multiple Teams](#free-for-alls-and-multiple-teams)
+//!     - [Expected Outcome](#expected-outcome)
+//!     - [Rating Period](#rating-period)
+//!     - [Switching between different rating systems](#switching-between-different-rating-systems)
+//! - [Contributing](#contributing)
+//! - [License](#license)
+//!
+//!
+//! ## Installation
 //!
 //! If you are on Rust 1.62 or higher use `cargo add` to install the latest version:
 //!
@@ -50,7 +66,7 @@
 //! skillratings = "0.25"
 //! ```
 //!
-//! ## Serde support
+//! ### Serde support
 //!
 //! Serde support is gated behind the `serde` feature. You can enable it like so:
 //!
@@ -67,7 +83,7 @@
 //! skillratings = {version = "0.25", features = ["serde"]}
 //! ```
 //!
-//! # Usage and Examples
+//! ## Usage and Examples
 //!
 //! Below you can find some basic examples of the use cases of this crate.  
 //! There are many more rating algorithms available with lots of useful functions that are not covered here.  
@@ -285,6 +301,64 @@
 //! // The rating of the player decreased by around ~40 points.
 //! assert_eq!(new_player.rating.round(), 1362.0);
 //! ```
+//!
+//! ### Switching between different rating systems
+//!
+//! If you want to switch between different rating systems, for example to compare results or do scientific analyisis,
+//! we provide the `Rating`, `RatingSystem` (1v1), `RatingPeriodSystem` (1v1 Tournaments), `TeamRatingSystem` (Team vs. Team)
+//! and `MultiTeamRatingSystem` (FFA) traits to make switching as easy as possible.
+//!
+//! In the following example, we are using the `RatingSystem` (1v1) Trait with Glicko-2:
+//!
+//! ```rust
+//! use skillratings::{
+//!     glicko2::{Glicko2, Glicko2Config},
+//!     Outcomes, Rating, RatingSystem,
+//! };
+//!
+//! // Initialise a new player rating with a rating value and uncertainty value.
+//! // Not every rating system has an uncertainty value, so it may be discarded.
+//! let player_one = Rating::new(Some(1200.0), Some(120.0));
+//! // If you want the default values for the rating system, use None instead.
+//! let player_two = Rating::new(None, None);
+//!
+//! // The config needs to be specific to the rating system.
+//! // When you swap rating systems, make sure to update the config.
+//! let config = Glicko2Config::new();
+//!
+//! // You may also need to use a type annotation here for the compiler.
+//! let rating_system: Glicko2 = RatingSystem::new(config);
+//!
+//! // The outcome of the match is from the perspective of player one.
+//! let outcome = Outcomes::WIN;
+//!
+//! // All rating systems share a `rate` function for performing the actual calculations,
+//! // plus an `expected_score` function for calculating the expected performances.
+//! // Some rating systems might have additional functions,
+//! // which are only available when you use them directly.
+//! let expected_score = rating_system.expected_score(&player_one, &player_two);
+//! let (new_one, new_two) = rating_system.rate(&player_one, &player_two, &outcome);
+//!
+//! // After that, you can access the players rating and uncertainty with the functions below.
+//! assert_eq!(new_one.rating().round(), 1241.0);
+//! // Note that because not every rating system has an uncertainty value,
+//! // the uncertainty function returns an Option<f64>.
+//! assert_eq!(new_one.uncertainty().unwrap().round(), 118.0);
+//! ```
+//!
+//! ## Contributing
+//!
+//! Contributions of any kind are always welcome!  
+//!
+//! Found a bug or have a feature request? [Submit a new issue](https://github.com/atomflunder/skillratings/issues/).  
+//! Alternatively, [open a pull request](https://github.com/atomflunder/skillratings/pulls) if you want to add features or fix bugs.  
+//! Leaving other feedback is of course also appreciated.
+//!
+//! Thanks to everyone who takes their time to contribute.
+//!
+//! ## License
+//!
+//! This project is licensed under either the [MIT License](/LICENSE-MIT), or the [Apache License, Version 2.0](/LICENSE-APACHE).
 
 #[cfg(feature = "serde")]
 use serde::de::DeserializeOwned;