Docs

View the documentation locally:

Mkdocs

To view the mkdocs site, run:

mkdocs serve

Unfortunately, there is currently no mkdocstrings plugin available for Rust, which means we can't easily include docstrings from the code in the docs site. Instead, we use cargo doc to generate separate reference docs from the docstrings in the code.

cargo watch -x "doc --no-deps"

Versioning

We use mike to manage versioning for our documentation. It creates a snapshot of the documentation for each version of the project, allowing users to access the appropriate docs for the version they're using—even if it's an older one.

Build new docs version

Build the docs for the current project version:

mike deploy $(cz version --project) latest --update-aliases

To push your new docs version:

mike deploy $(cz version --project) latest --update-aliases --push

The first time you use Mike, you'll need to tell it which version is the default (the one it shows when you load the docs main page). We'll set it to the "default" alias:

mike set-default latest

To list the available docs versions:

mike list 

To view the versioned docs locally (with a drop-down to select which docs version you want):

mike serve 

Writing

These are some tools you can use to enrich the documentation.

Diagrams

Mermaid diagrams can be written in a mermaid code block, and they will be rendered as diagrams:

Graphs:

graph LR
    hello --> world
    world --> again
    again --> hello

Sequence diagrams:

sequenceDiagram
  autonumber
  Alice->>John: Hello John, how are you?
  loop Healthcheck
      John->>John: Fight against hypochondria
  end
  Note right of John: Rational thoughts!
  John-->>Alice: Great!
  John->>Bob: How about you?
  Bob-->>John: Jolly good!

Class diagrams:

classDiagram
  Person <|-- Student
  Person <|-- Professor
  Person : +String name
  Person : +String phoneNumber
  Person : +String emailAddress
  Person: +purchaseParkingPass()
  Address "1" <-- "0..1" Person:lives at
  class Student{
    +int studentNumber
    +int averageMark
    +isEligibleToEnrol()
    +getSeminarsTaken()
  }
  class Professor{
    +int salary
  }
  class Address{
    +String street
    +String city
    +String state
    +int postalCode
    +String country
    -validate()
    +outputAsLabel()  
  }

Tooltips

Tooltips and other such "admonitions" can be written with a !!! block:

!!! note
    This is a note.

Code blocks

Specify python with the "py" shortcode after the 3 backticks. You can highlight lines too with hl_lines="3-5"

/// Divides the first number by the second and returns the result.
///
/// # Panics
///
/// Panics if the second number is zero.
///
/// # Examples
///
/// ```
/// let result = binnev_rust_template::divide(6.0, 3.0);
/// assert_eq!(result, 2.0);
/// ```
pub fn divide(a: f64, b: f64) -> f64 {
    if b == 0.0 {
        panic!("Cannot divide by zero");
    }
    a / b
}

Inline code blocks can be highlighted for specific languages by prefixing #!python: lambda a: print(a)

Content tabs

Content tabs can be used to show different versions of something in a tabbed layout:

#include <stdio.h>

int main(void) {
  printf("Hello world!\n");
  return 0;
}

#include <iostream>

int main(void) {
  std::cout << "Hello world!" << std::endl;
  return 0;
}

It doesn't have to be code: