

Creating a tutorial with a runnable program¶

Create a minimal working program.¶

fn main() {
    println!("Hello world");
}

Break the code up anywhere you think needs explanation.¶

For example¶

The main function that runs the program.

fn main() {

Print to the console.

    println!("Hello world");
}

Add in features with explanation.¶

The mark \#S: tells single source that we have some flags for it. The INCLUDE flag tells single source to include any code from here on unless it gets a SKIP flag.

For example¶

#S:INCLUDE This struct is used to store a static str.

#[derive(Debug)]
struct HelloWorld {
    text: &'static str,
}

Include / Skip / Hide code.¶

All rust code will be included at this point in the document but you might want to skip some code from using in your program.

For example¶

#S:SKIP We could also write this as:

#[derive(Debug)]
struct HelloWorld {

Storing the text as a String.

    text: String, 
}

The previous two block will not be included in the program. To include code you need to: #S:INCLUDE

fn main() {
    let hello_world = HelloWorld {
        text: HELLO_WORLD,
    };
    println!("{:?}", hello_world);
}

Then maybe you want to add some code that will be included but not visible in the tutorial.

Note that HIDE will only hide the block directly following.

#S:HIDE

const HELLO_WORLD: &'static str = "HELLO_WORLD";

Run and build the program.¶

Build the program.

single_source code docs/runnable_tutorial.md ~/rust/test_tutorial/src/main.rs rust

Build the documentation.

single_source md docs/runnable_tutorial.md docs/runnable_tutorial_rendered.md

You can also render a check in the document to see what the code looks like.

#S:CHECK=rust