Documentation (#3)

* Finish starting page

* Docs

* Prepare release and gh actions

.github/workflows/rust.yml

@@ -34,4 +34,4 @@ jobs:
     - name: Build
       run: cargo build
     - name: Run tests
-      run: cargo test
+      run: cargo test --lib

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "genanki-rs"
-version = "0.0.2"
+version = "0.1.0"
 authors = ["Yannick Funk <yannickfunk@yahoo.de>"]
 edition = "2018"
 description = "Crate to create decks for the open source flashcard platform Anki. Based on Python library genanki"

README.md

@@ -12,7 +12,7 @@ With `genanki-rs` you can easily generate decks for the popular open source flas
 Add 
 ```toml
 [dependencies]
-genanki-rs = "0.0.2"
+genanki-rs = "0.1.0"
 ```
 to your `Cargo.toml` or find another version on [*crates.io*](https://crates.io/crates/genanki-rs)
 

src/builders/field.rs

@@ -1,5 +1,23 @@
 use crate::db_entries::Fld;
 
+/// Field to be fed into a `Model`.
+///
+/// A `Field` can be created using the builder pattern.
+///
+/// Example:
+///
+/// ```rust
+/// use genanki_rs::Field;
+///
+/// let field1 = Field::new("field1");
+/// let field2 = Field::new("field2").font("Comic Sans").size(15);
+/// ```
+///
+/// The builder has the following default values:
+/// * `sticky` - `false`
+/// * `rtl` - `false`
+/// * `font` - `Liberation Sans`
+/// * `size` - `20`
 #[derive(Clone)]
 pub struct Field {
     name: String,
@@ -10,6 +28,7 @@ pub struct Field {
 }
 
 impl Field {
+    /// Creates a new field with a `name`
     pub fn new(name: &str) -> Self {
         Self {
             name: name.to_string(),
@@ -20,21 +39,25 @@ impl Field {
         }
     }
 
+    /// Sets the font of the `Field` which is currently created
     pub fn font(mut self, value: &str) -> Self {
         self.font = Some(value.to_string());
         self
     }
 
+    /// Sets whether the currently created `Field` is right-to-left or not
     pub fn rtl(mut self, value: bool) -> Self {
         self.rtl = Some(value);
         self
     }
 
+    /// Sets whether the currently created `Field` is sticky or not
     pub fn sticky(mut self, value: bool) -> Self {
         self.sticky = Some(value);
         self
     }
 
+    /// Sets the font size of the currently created `Field`
     pub fn size(mut self, value: i64) -> Self {
         self.size = Some(value);
         self

src/builders/template.rs

@@ -1,5 +1,17 @@
 use crate::db_entries::Tmpl;
 
+/// Template to be fed into a `Model`.
+/// A Template represents the structure of `Notes` (Flashcards) in the deck and can be created using
+/// the builder pattern.
+///
+/// Example:
+/// ```rust
+/// use genanki_rs::Template;
+///
+/// let template1 = Template::new("Card 1").qfmt("{{Question}}").afmt(r#"{{FrontSide}}<hr id="answer">{{Answer}}"#);
+/// let template2 = Template::new("Card 2").qfmt("{{Back}}").afmt("{{FrontSide}}\n\n<hr id=answer>\n\n{{Front}}");
+/// ```
+///
 #[derive(Clone)]
 pub struct Template {
     name: String,
@@ -11,6 +23,7 @@ pub struct Template {
 }
 
 impl Template {
+    /// Creates a new `Template` with a `name`
     pub fn new(name: &str) -> Self {
         Self {
             name: name.to_string(),
@@ -22,26 +35,31 @@ impl Template {
         }
     }
 
+    /// Sets the question format of the currently created `Template`
     pub fn qfmt(mut self, qfmt: &str) -> Self {
         self.qfmt = Some(qfmt.to_string());
         self
     }
 
+    /// Sets the deck id of the currently created `Template`
     pub fn did(mut self, did: usize) -> Self {
         self.did = Some(did);
         self
     }
 
+    /// Sets the browser answer format of the currently created `Template`
     pub fn bafmt(mut self, bafmt: &str) -> Self {
         self.bafmt = Some(bafmt.to_string());
         self
     }
 
+    /// Sets the answer format of the currently created `Template`
     pub fn afmt(mut self, afmt: &str) -> Self {
         self.afmt = Some(afmt.to_string());
         self
     }
 
+    /// Sets the browser question format of the currently created template
     pub fn bqfmt(mut self, bqfmt: &str) -> Self {
         self.bqfmt = Some(bqfmt.to_string());
         self

src/card.rs

@@ -11,7 +11,7 @@ impl Card {
     pub fn new(ord: i64, suspend: bool) -> Self {
         Self { ord, suspend }
     }
-
+    #[allow(dead_code)]
     pub fn ord(&self) -> i64 {
         self.ord
     }

src/deck.rs

@@ -6,6 +6,7 @@ use rusqlite::{params, Transaction};
 use std::collections::HashMap;
 use std::ops::RangeFrom;
 
+/// A flashcard deck which can be written into an .apkg file.
 #[derive(Clone)]
 pub struct Deck {
     id: usize,
@@ -16,6 +17,9 @@ pub struct Deck {
 }
 
 impl Deck {
+    /// Creates a new deck with an `id`, `name` and `description`.
+    ///
+    /// `id` should always be unique when creating multiple decks.
     pub fn new(id: usize, name: &str, description: &str) -> Self {
         Self {
             id,
@@ -26,15 +30,25 @@ impl Deck {
         }
     }
 
+    /// Adds a `note` (Flashcard) to the deck.
+    ///
+    /// Example:
+    ///
+    /// ```rust
+    /// use genanki_rs::{Deck, Note, basic_model};
+    ///
+    /// let mut my_deck = Deck::new(1234, "Example deck", "This is an example deck");
+    /// my_deck.add_note(Note::new(basic_model(), vec!["What is the capital of France?", "Paris"])?);
+    /// ```
     pub fn add_note(&mut self, note: Note) {
         self.notes.push(note);
     }
 
-    pub fn add_model(&mut self, model: Model) {
+    fn add_model(&mut self, model: Model) {
         self.models.insert(model.id, model);
     }
 
-    pub fn to_deck_db_entry(&self) -> DeckDbEntry {
+    fn to_deck_db_entry(&self) -> DeckDbEntry {
         DeckDbEntry {
             collapsed: false,
             conf: 1,
@@ -52,12 +66,14 @@ impl Deck {
             usn: -1,
         }
     }
-    pub fn to_json(&self) -> String {
+
+    #[allow(dead_code)]
+    fn to_json(&self) -> String {
         let db_entry: DeckDbEntry = self.to_deck_db_entry();
         serde_json::to_string(&db_entry).expect("Should always serialize")
     }
 
-    pub fn write_to_db(
+    pub(super) fn write_to_db(
         &mut self,
         transaction: &Transaction,
         timestamp: f64,
@@ -91,6 +107,29 @@ impl Deck {
         Ok(())
     }
 
+    /// Packages a deck and writes it to a new `.apkg` file. This file can then be imported in Anki.
+    ///
+    /// Returns `Err` if the file can not be created.
+    ///
+    /// Example:
+    /// ```rust
+    /// use genanki_rs::{Deck, Note, basic_model};
+    ///
+    /// let mut my_deck = Deck::new(1234, "Example deck", "This is an example deck");
+    /// my_deck.add_note(Note::new(basic_model(), vec!["What is the capital of France?", "Paris"])?);
+    ///
+    /// my_deck.write_to_file("output.apkg")?;
+    /// ```
+    ///
+    /// This is equivalent to:
+    /// ```rust
+    /// use genanki_rs::{Deck, Note, basic_model, Package};
+    ///
+    /// let mut my_deck = Deck::new(1234, "Example deck", "This is an example deck");
+    /// my_deck.add_note(Note::new(basic_model(), vec!["What is the capital of France?", "Paris"])?);
+    ///
+    /// Package::new(vec![my_deck], vec![])?.write_to_file("output.apkg")?;
+    /// ```
     pub fn write_to_file(self, file: &str) -> Result<(), anyhow::Error> {
         Package::new(vec![self], vec![])?.write_to_file(file)?;
         Ok(())