Make hiding and showing of setup code in code examples more obvious

[brendanzab]

Just came across this in the Kotlin docs - they let you hide and show the setup code in examples:

Very slick!

It seems that instead of the # comments like we currently have for hiding code lines, they use special comments to mark the beginning and end of samples:

//sampleStart
fun sum(a: Int, b: Int): Int {
    return a + b
}
//sampleEnd

fun main(args: Array<String>) {
    print("sum of 3 and 5 is ")
    println(sum(3, 5))
}

Also note that code is re-indented as necessary:

fun main(args: Array<String>) {
    val fruits = listOf("banana", "avocado", "apple", "kiwifruit")
//sampleStart
    fruits
        .filter { it.startsWith("a") }
        .sortedBy { it }
        .map { it.toUpperCase() }
        .forEach { println(it) }
//sampleEnd
}

---

Edit

I didn't actually realise you could hide/show code in mdBook, but it seems you can! Alas it's hidden behind a non-obvious icon that I interpreted to mean 'fullscreen':

Also, the Kotlin examples have a different background behind the setup code in the expanded mode, which is really nice touch. Makes the setup code recede into the background, and you don't have to remember so much what the original example looked like. The is very handy for more involved examples.

[steveklabnik]

This already exists today http://rust-lang-nursery.github.io/mdBook/format/mdbook.html#hiding-code-lines

[steveklabnik]

Oh, you want a new, additional syntax. Sorry! I missed that.

[brendanzab]

Yup, also see how the reader can expand the example to see the setup. This is nice, because the author can focus in on a specific point, while still allowing folks to copy-paste a working thing if they want to.

[steveklabnik]

That's already in there today; this would purely be about the new comment style.

[brendanzab]

OHH, we're talking about the 'fullscreen' icon here?

I thought it was a full screen icon, so I never tried clicking on it. Also, it would be nice to have some styling that separated the hidden code from the non-hidden code in the expanded mode. The UX design on the Kotlin docs seems to have been nicely thought through in that respect.

I do understand that there might have been time and resource allocation constraints when the feature was first added. But yeah, all the more reason to be inspired by other people's good ideas!

[brendanzab]

Updated the title and issue description to reflect the discussion!

[brendanzab]

I would say that one issue with the # syntax is that it's hard to get the indentation right in examples when programming in a way where you're assuming that somebody might see it (by clicking the expand icon).

Also, does Rustdoc fix the indentation of stuff like:

#fn main() {
    println!("hi");
#}

So that it renders like this in the collapsed mode:

println!("hi");

And not this:

    println!("hi");

[steveklabnik]

It's too hard to fix in the general case, so we don't deal with indentation at all.

[onelson]

Just wanted to echo the sentiment here:

Alas it's hidden behind a non-obvious icon that I interpreted to mean 'fullscreen':

It took me a long time to notice that icon, then to not dismiss it as something like "open in a new window" or "fullscreen" to the point where I actually hovered over and saw the title.

Sharing the fact this feature exists with others has made me feel popular and smart, but this definitely seems like the icon could be working harder to promote itself.

An "eye" icon in open and closed variants was suggested and makes a lot of sense to me.

[ashneverdawn]

Wow just found out about the hidden-code-lines! I think an icon similar to https://image.flaticon.com/icons/png/512/56/56181.png would be more appropriate.

But yeah, the way it is in the Kotlin docs is really nice! Much more intuitive.

[ashneverdawn]

I believe this is what we'd use:

• https://fontawesome.com/v4.7.0/icon/eye-slash
• https://fontawesome.com/v4.7.0/icon/eye