Fixing code examples, statement about working tests on code examples

[llogiq]

This doctests all code examples. There is some fallout to either ignore examples (if I deemed them too far from runnable) or change them to work, or at least compile.

I also added a .travis.yml so we can use CI to check PRs.

fixes #49

[nrc]

Hmm, I wonder how worthwhile this is - it found one bug (which is nice), but I feel like every example which gets changed has got more cluttered and less easily understandable and that doesn't feel like a great trade-off to me.

[lambda-fairy]

Rustdoc lets you hide setup code by prefixing it with #, but I'm not sure how that'll help in our case.

[llogiq]

I see two ways going forward:

• write a build script that skips lines starting with # within code blocks, publish to github-pages
• create an examples subdirectory containing complete runnable examples that can be playpen-linked, link them from the inline-examples.

Perhaps we can even do both and have the script build the examples?

[lambda-fairy]

See also #6 and #44. It would be nice to publish this to a standalone website one day.

Having a separate examples directory doesn't feel right, somehow. I think it's because the examples are so short that splitting them out into separate files won't be worth the extra effort. Maintaining a separate set of examples may raise the barrier to entry for contributors as well.

Also, since rustbook is built on top of rustdoc, I think it'll strip # lines already.

[llogiq]

The idea is to have playground links. I'm not sure if this requires a canonical location per example or if the code gets embedded as link data.

[lambda-fairy]

Okay, I see what you're aiming for with the playground.

As prior art, the official Rust book has playground links -- e.g. see the section on lifetimes. It looks like they use the # prefix solution, displaying the pretty code in the book but linking to the full code on the playground.

Unless there are further issues with their approach, I'm keen to just copy what they do.

[llogiq]

Agreed. I'll look into that. Perhaps I should pare down this PR to the one fix I found then.

[pickfire]

Ping

[simonsan]

Small feedback (imho): I think it would be better at this stage to use Github Actions for that instead of Travis.

See next comment.

[lambda-fairy]

mdbook has a built-in doctest feature as well, which would make this PR redundant.

https://rust-lang.github.io/mdBook/cli/test.html

[simonsan]

mdbook has a built-in doctest feature as well, which would make this PR redundant.

https://rust-lang.github.io/mdBook/cli/test.html

Thanks for the heads-up, indeed, that looks like it would make it redundant when we convert this into a mdbook.

ref.: #6

[simonsan]

Seems good to me, @marcoieni any additions?

[simonsan]

Hey @llogiq is there any reason you're closing this? There are still changes to be merged from your PR that are not the concerning the doctests or Travis, I already edited your branch to remove the parts and changed the title.

[simonsan]

Added the statement of working code examples to the template.md in #123 . What about the additions to the examples and rust, ignore? Do we still want to merge that from this PR?

Added them in #124