Created READMEs for observers and checkpointing, updated docs

stefan-k · Feb 19, 2024 · d44f58b · d44f58b
1 parent e45e701
commit d44f58b
Show file tree

Hide file tree

Showing 11 changed files with 478 additions and 10 deletions.
diff --git a/crates/argmin-checkpointing-file/README.md b/crates/argmin-checkpointing-file/README.md
@@ -0,0 +1,64 @@
+<p align="center">
+  <img
+    width="400"
+    src="https://raw.githubusercontent.com/argmin-rs/argmin/main/media/logo.png"
+  />
+</p>
+<h1 align="center">argmin-checkpointing-file</h1>
+
+<p align="center">
+  <a href="https://argmin-rs.org">Website</a>
+  |
+  <a href="https://argmin-rs.org/book/">Book</a>
+  |
+  <a href="https://docs.rs/argmin-checkpointing-file">Docs (latest release)</a>
+  |
+  <a href="https://argmin-rs.github.io/argmin/argmin_checkpointing_file/index.html">Docs (main branch)</a>
+</p>
+
+<p align="center">
+  <a href="https://crates.io/crates/argmin-checkpointing-file"
+    ><img
+      src="https://img.shields.io/crates/v/argmin-checkpointing-file?style=flat-square"
+      alt="Crates.io version"
+  /></a>
+  <a href="https://crates.io/crates/argmin-checkpointing-file"
+    ><img
+      src="https://img.shields.io/crates/d/argmin-checkpointing-file?style=flat-square"
+      alt="Crates.io downloads"
+  /></a>
+  <a href="https://github.com/argmin-rs/argmin/actions"
+    ><img
+      src="https://img.shields.io/github/actions/workflow/status/argmin-rs/argmin/ci.yml?branch=main&label=argmin CI&style=flat-square"
+      alt="GitHub Actions workflow status"
+  /></a>
+  <img
+    src="https://img.shields.io/crates/l/argmin-checkpointing-file?style=flat-square"
+    alt="License"
+  />
+  <a href="https://discord.gg/fYB8AwxxMW"
+    ><img
+      src="https://img.shields.io/discord/1189119565335109683?style=flat-square&label=argmin%20Discord"
+      alt="argmin Discord"
+  /></a>
+</p>
+
+Saves a checkpoint on disk from which an interrupted optimization run can be resumed.
+For details on the usage please see the documentation ([latest release](https://docs.rs/argmin-checkpointing-file)
+or [current main](https://argmin-rs.github.io/argmin/argmin_checkpointing_file/index.html))
+or the [argmin book](https://argmin-rs.org/book/) or have a look at
+the [example](https://github.com/argmin-rs/argmin/tree/main/examples/checkpoint).
+
+## License
+
+Licensed under either of
+
+  * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+  * MIT License ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+
+at your option.
+
+### Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you,
+as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
diff --git a/crates/argmin-checkpointing-file/src/lib.rs b/crates/argmin-checkpointing-file/src/lib.rs
@@ -5,6 +5,39 @@
 // http://opensource.org/licenses/MIT>, at your option. This file may not be
 // copied, modified, or distributed except according to those terms.
 
+//! This crate creates checkpoints on disk for an optimization run.
+//!
+//! Saves a checkpoint on disk from which an interrupted optimization run can be resumed.
+//! For details on the usage please see the documentation of [`FileCheckpoint`] or have a look at
+//! the [example](https://github.com/argmin-rs/argmin/tree/main/examples/checkpoint).
+//!
+//! # Usage
+//!
+//! Add the following line to your dependencies list:
+//!
+//! ```toml
+//! [dependencies]
+#![doc = concat!("argmin-checkpointing-file = \"", env!("CARGO_PKG_VERSION"), "\"")]
+//! ```
+//!
+//! # License
+//!
+//! Licensed under either of
+//!
+//!   * Apache License, Version 2.0,
+//!     ([LICENSE-APACHE](https://github.com/argmin-rs/argmin/blob/main/LICENSE-APACHE) or
+//!     <http://www.apache.org/licenses/LICENSE-2.0>)
+//!   * MIT License ([LICENSE-MIT](https://github.com/argmin-rs/argmin/blob/main/LICENSE-MIT) or
+//!     <http://opensource.org/licenses/MIT>)
+//!
+//! at your option.
+//!
+//! ## Contribution
+//!
+//! Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion
+//! in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above,
+//! without any additional terms or conditions.
+
 pub use argmin::core::checkpointing::{Checkpoint, CheckpointingFrequency};
 use argmin::core::Error;
 use serde::{de::DeserializeOwned, Serialize};

diff --git a/crates/argmin-observer-paramwriter/Cargo.toml b/crates/argmin-observer-paramwriter/Cargo.toml
@@ -15,7 +15,7 @@ exclude = []
 
 [dependencies]
 argmin = { version = "0.9.0", path = "../argmin", default-features = false }
-bincode = { version = "1.3.3" }
+bincode = { version = "1.3" }
 serde = { version = "1.0", features = ["derive", "rc"] }
 serde_json = { version = "1.0" }
 

diff --git a/crates/argmin-observer-paramwriter/README.md b/crates/argmin-observer-paramwriter/README.md
@@ -0,0 +1,65 @@
+<p align="center">
+  <img
+    width="400"
+    src="https://raw.githubusercontent.com/argmin-rs/argmin/main/media/logo.png"
+  />
+</p>
+<h1 align="center">argmin-observer-paramwriter</h1>
+
+<p align="center">
+  <a href="https://argmin-rs.org">Website</a>
+  |
+  <a href="https://argmin-rs.org/book/">Book</a>
+  |
+  <a href="https://docs.rs/argmin-observer-paramwriter">Docs (latest release)</a>
+  |
+  <a href="https://argmin-rs.github.io/argmin/argmin_observer_paramwriter/index.html">Docs (main branch)</a>
+</p>
+
+<p align="center">
+  <a href="https://crates.io/crates/argmin-observer-paramwriter"
+    ><img
+      src="https://img.shields.io/crates/v/argmin-observer-paramwriter?style=flat-square"
+      alt="Crates.io version"
+  /></a>
+  <a href="https://crates.io/crates/argmin-observer-paramwriter"
+    ><img
+      src="https://img.shields.io/crates/d/argmin-observer-paramwriter?style=flat-square"
+      alt="Crates.io downloads"
+  /></a>
+  <a href="https://github.com/argmin-rs/argmin/actions"
+    ><img
+      src="https://img.shields.io/github/actions/workflow/status/argmin-rs/argmin/ci.yml?branch=main&label=argmin CI&style=flat-square"
+      alt="GitHub Actions workflow status"
+  /></a>
+  <img
+    src="https://img.shields.io/crates/l/argmin-observer-paramwriter?style=flat-square"
+    alt="License"
+  />
+  <a href="https://discord.gg/fYB8AwxxMW"
+    ><img
+      src="https://img.shields.io/discord/1189119565335109683?style=flat-square&label=argmin%20Discord"
+      alt="argmin Discord"
+  /></a>
+</p>
+
+This argmin observer writes serialized parameter vectors to files during optimization.
+Details can be found in the documentation ([latest release](https://docs.rs/argmin-observer-paramwriter) or 
+[current main](https://argmin-rs.github.io/argmin/argmin_observer_paramwriter/index.html))
+or the [argmin book](https://argmin-rs.org/book/). 
+There is also an [example](https://github.com/argmin-rs/argmin/tree/main/examples/paramwriter)
+which illustrates how to use the observer.
+
+## License
+
+Licensed under either of
+
+  * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+  * MIT License ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+
+at your option.
+
+### Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you,
+as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
diff --git a/crates/argmin-observer-paramwriter/src/lib.rs b/crates/argmin-observer-paramwriter/src/lib.rs
@@ -5,9 +5,36 @@
 // http://opensource.org/licenses/MIT>, at your option. This file may not be
 // copied, modified, or distributed except according to those terms.
 
-//! # Write parameter vectors to a file during optimization.
+//! Writes parameter vectors to a file during optimization.
 //!
 //! See documentation of [`ParamWriter`] and [`ParamWriterFormat`] for details.
+//!
+//! # Usage
+//!
+//! Add the following line to your dependencies list:
+//!
+//! ```toml
+//! [dependencies]
+#![doc = concat!("argmin-observer-paramwriter = \"", env!("CARGO_PKG_VERSION"), "\"")]
+//! ```
+//!
+//! # License
+//!
+//! Licensed under either of
+//!
+//!   * Apache License, Version 2.0,
+//!     ([LICENSE-APACHE](https://github.com/argmin-rs/argmin/blob/main/LICENSE-APACHE) or
+//!     <http://www.apache.org/licenses/LICENSE-2.0>)
+//!   * MIT License ([LICENSE-MIT](https://github.com/argmin-rs/argmin/blob/main/LICENSE-MIT) or
+//!     <http://opensource.org/licenses/MIT>)
+//!
+//! at your option.
+//!
+//! ## Contribution
+//!
+//! Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion
+//! in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above,
+//! without any additional terms or conditions.
 
 use argmin::core::observers::Observe;
 use argmin::core::{Error, State, KV};

diff --git a/crates/argmin-observer-slog/README.md b/crates/argmin-observer-slog/README.md
@@ -0,0 +1,63 @@
+<p align="center">
+  <img
+    width="400"
+    src="https://raw.githubusercontent.com/argmin-rs/argmin/main/media/logo.png"
+  />
+</p>
+<h1 align="center">argmin-observer-slog</h1>
+
+<p align="center">
+  <a href="https://argmin-rs.org">Website</a>
+  |
+  <a href="https://argmin-rs.org/book/">Book</a>
+  |
+  <a href="https://docs.rs/argmin-observer-slog">Docs (latest release)</a>
+  |
+  <a href="https://argmin-rs.github.io/argmin/argmin_observer_slog/index.html">Docs (main branch)</a>
+</p>
+
+<p align="center">
+  <a href="https://crates.io/crates/argmin-observer-slog"
+    ><img
+      src="https://img.shields.io/crates/v/argmin-observer-slog?style=flat-square"
+      alt="Crates.io version"
+  /></a>
+  <a href="https://crates.io/crates/argmin-observer-slog"
+    ><img
+      src="https://img.shields.io/crates/d/argmin-observer-slog?style=flat-square"
+      alt="Crates.io downloads"
+  /></a>
+  <a href="https://github.com/argmin-rs/argmin/actions"
+    ><img
+      src="https://img.shields.io/github/actions/workflow/status/argmin-rs/argmin/ci.yml?branch=main&label=argmin CI&style=flat-square"
+      alt="GitHub Actions workflow status"
+  /></a>
+  <img
+    src="https://img.shields.io/crates/l/argmin-observer-slog?style=flat-square"
+    alt="License"
+  />
+  <a href="https://discord.gg/fYB8AwxxMW"
+    ><img
+      src="https://img.shields.io/discord/1189119565335109683?style=flat-square&label=argmin%20Discord"
+      alt="argmin Discord"
+  /></a>
+</p>
+
+This argmin observer logs the progress of the optimization to the terminal or to disk.
+Details can be found in the documentation ([latest release](https://docs.rs/argmin-observer-slog) or 
+[current main](https://argmin-rs.github.io/argmin/argmin_observer_slog/index.html))
+or the [argmin book](https://argmin-rs.org/book/). 
+
+## License
+
+Licensed under either of
+
+  * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+  * MIT License ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+
+at your option.
+
+### Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you,
+as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
diff --git a/crates/argmin-observer-slog/src/lib.rs b/crates/argmin-observer-slog/src/lib.rs
@@ -5,12 +5,39 @@
 // http://opensource.org/licenses/MIT>, at your option. This file may not be
 // copied, modified, or distributed except according to those terms.
 
-//! # Loggers based on the `slog` crate
+//! This crate contains loggers based on the `slog` crate.
 //!
 //! These loggers write general information about the optimization and information about the
 //! progress of the optimization for each iteration of the algorithm to screen or into a file in
 //! JSON format.
 //! See [`SlogLogger`] for details regarding usage.
+//!
+//! # Usage
+//!
+//! Add the following line to your dependencies list:
+//!
+//! ```toml
+//! [dependencies]
+#![doc = concat!("argmin-observer-slog = \"", env!("CARGO_PKG_VERSION"), "\"")]
+//! ```
+//!
+//! # License
+//!
+//! Licensed under either of
+//!
+//!   * Apache License, Version 2.0,
+//!     ([LICENSE-APACHE](https://github.com/argmin-rs/argmin/blob/main/LICENSE-APACHE) or
+//!     <http://www.apache.org/licenses/LICENSE-2.0>)
+//!   * MIT License ([LICENSE-MIT](https://github.com/argmin-rs/argmin/blob/main/LICENSE-MIT) or
+//!     <http://opensource.org/licenses/MIT>)
+//!
+//! at your option.
+//!
+//! ## Contribution
+//!
+//! Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion
+//! in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above,
+//! without any additional terms or conditions.
 
 use argmin::core::observers::Observe;
 use argmin::core::{Error, State, KV};

diff --git a/crates/argmin-observer-spectator/README.md b/crates/argmin-observer-spectator/README.md
@@ -0,0 +1,65 @@
+<p align="center">
+  <img
+    width="400"
+    src="https://raw.githubusercontent.com/argmin-rs/argmin/main/media/logo.png"
+  />
+</p>
+<h1 align="center">argmin-observer-spectator</h1>
+
+<p align="center">
+  <a href="https://argmin-rs.org">Website</a>
+  |
+  <a href="https://argmin-rs.org/book/">Book</a>
+  |
+  <a href="https://docs.rs/argmin-observer-spectator">Docs (latest release)</a>
+  |
+  <a href="https://argmin-rs.github.io/argmin/argmin_observer_spectator/index.html">Docs (main branch)</a>
+</p>
+
+<p align="center">
+  <a href="https://crates.io/crates/argmin-observer-spectator"
+    ><img
+      src="https://img.shields.io/crates/v/argmin-observer-spectator?style=flat-square"
+      alt="Crates.io version"
+  /></a>
+  <a href="https://crates.io/crates/argmin-observer-spectator"
+    ><img
+      src="https://img.shields.io/crates/d/argmin-observer-spectator?style=flat-square"
+      alt="Crates.io downloads"
+  /></a>
+  <a href="https://github.com/argmin-rs/argmin/actions"
+    ><img
+      src="https://img.shields.io/github/actions/workflow/status/argmin-rs/argmin/ci.yml?branch=main&label=argmin CI&style=flat-square"
+      alt="GitHub Actions workflow status"
+  /></a>
+  <img
+    src="https://img.shields.io/crates/l/argmin-observer-spectator?style=flat-square"
+    alt="License"
+  />
+  <a href="https://discord.gg/fYB8AwxxMW"
+    ><img
+      src="https://img.shields.io/discord/1189119565335109683?style=flat-square&label=argmin%20Discord"
+      alt="argmin Discord"
+  /></a>
+</p>
+
+This observer sends metrics and parameter vectors to a Spectator instance.
+For details on the usage please see the documentation ([latest release](https://docs.rs/argmin-observer-spectator)
+or [current main](https://argmin-rs.github.io/argmin/argmin_observer_spectator/index.html))
+or the [argmin book](https://argmin-rs.org/book/) or have a look at
+the [example 1](https://github.com/argmin-rs/argmin/tree/main/examples/spectator_basic)
+and the [example 2](https://github.com/argmin-rs/argmin/tree/main/examples/spectator_multiple).
+
+## License
+
+Licensed under either of
+
+  * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+  * MIT License ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+
+at your option.
+
+### Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you,
+as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
diff --git a/crates/argmin-observer-spectator/src/lib.rs b/crates/argmin-observer-spectator/src/lib.rs
@@ -5,8 +5,6 @@
 // http://opensource.org/licenses/MIT>, at your option. This file may not be
 // copied, modified, or distributed except according to those terms.
 
-//! # Observer for Spectator
-//!
 //! This observer sends metrics and parameter vectors to a Spectator instance.
 //!
 //! ## Example