Closed llogiq closed 3 years ago
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.
Rustdoc lets you hide setup code by prefixing it with #
, but I'm not sure how that'll help in our case.
I see two ways going forward:
build script
that skips lines starting with #
within code blocks, publish to github-pagesexamples
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
?
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.
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.
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.
Agreed. I'll look into that. Perhaps I should pare down this PR to the one fix I found then.
Ping
Small feedback (imho): I think it would be better at this stage to use Github Actions for that instead of Travis.
See next comment.
mdbook has a built-in doctest feature as well, which would make this PR redundant.
mdbook has a built-in doctest feature as well, which would make this PR redundant.
Thanks for the heads-up, indeed, that looks like it would make it redundant when we convert this into a mdbook
.
ref.: #6
Seems good to me, @MarcoIeni any additions?
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.
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
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