Comments (25)
Yes, great idea :)
Have you a rough idea of how much work that represents?
Also, I have not tested extensively, but I think there is no syntax highlighting. I am not sure if the markdown crate I use supports it. Otherwise I will have pre- / post-process or use another markdown parser.
from mdbook.
Ace is the method playpen and rustbyexample use for embedding a text editor which in of itself isn't that difficult. Editor syntax highlighting is handled by ace. All you have to do is choose the theme.
Regarding processing, rustbyexample loads the examples from *.rs
files and pipes them to the rust playpen via JSON api which the playpen then runs and returns output. The output is then formatted by rustbyexample and attached to the end as results I think.
Also, rustbyexample uses a {*.play}
syntax for stating there is a rust file underneath which needs to be sent to playpen and loaded. So, the rust file doesn't need to be parsed out via markdown if you follow some similar course.
I hope that's helpful.
from mdbook.
Yes, thank you for the explanation.
I can't guarantee the same syntax {*.play}
but I will try to see if I can make a handlebar helper.
Something that may look like:
Would that be ok?
I am not very familiar with handlebars so I don't know what is possible and what is not.
Edit:
I also considered, letting users add their own handlebar helpers so that they can have 100% control. But I am not sure how complicated that is. If I was able to implement that, would that let you implement what you need?
from mdbook.
I don't think it's important if it is {*.play}
or {{#...}}
or otherwise, just that the files are loaded external from the markdown. If that uses {{...}}
, that's fine.
Another thing. rustbyexample uses extensive example sets which must be testable. Currently it's done via the make
build system. It'd be pretty great if mdBook
made it as nice as cargo test
. That may not under your control though but I thought I'd mention it.
from mdbook.
I don't really understand what you mean with the second paragraph, could you explain a little bit more?
from mdbook.
All the rustbyexample examples are composed of markdown files and rust files which makes nice documentation. The problem is when when rust is upgraded, some examples may start throwing warnings or errors when they are run because rust has been updated and some rust function was deprecated or renamed. To get around that, the make build system that is used manually searches the examples tree for rust files and compiles them with rustc to test to see if there are any warnings or errors.
Part of the problem is I think we could migrate to annotating the examples in the Cargo.toml
so cargo would test them but that would require keeping two lists of examples. One for gitbook and one for cargo to test the examples with (probably in the Cargo.toml
). Gfx-rs annotates their testable examples somewhat like I was thinking for example (the same in rbe would be a horrible nightmare without toml-lang/toml#235).
Anyway, what would be really nice is if it was easy to setup so that when the structure of the document was laid out, any rust files which ended up being used got compiled via cargo test
. This is probably outside the scope of this problem though.
I hope that is a little more clear.
from mdbook.
Yes I understand know, but isn't that better implemented on their side?
My goal is to expose all the functionality as a library (aside from a cli) so on their side they could just add this crate to their dependencies and wrap the build in some function that executes the tests etc..
I am actually just now looking at what I should expose and how, so any feedback on that would be very useful. Once that step is done I work a little bit on the docs and I can publish a first version on Crates.io
from mdbook.
That's why I said it might not be under your control though it'd definitely be handy. Either way, it's probably outside the scope of what you'd want to do currently.
from mdbook.
Status update
In the playpen
branch you can now include rust files using
They will be displayed as all other code snippets inserted with markdown back ticks, except they have an additional playpen
css class. They are not yet runnable nor editable.
If someone wants to battleproof, that would be awesome! :)
What's next?
I will begin with non editable but playable rust snippets, the rust code for this should be mostly done. Now it's mainly javascript:
- Add a play button to all code snippets with the playpen class
- Bind the click event of the play button to send Ajax request to playpen
- Add output when playpen responds
After that we can start working on editable snippets.
from mdbook.
That went a lot faster than expected :)
We now have fully runnable examples! Not yet editable though. I am going to merge this in master already, the feature, as is, could already be useful.
Editable snippets
The idea is to support both editable and non-editable code snippets that can be runned.
The non editable snippets are already here, they look the same as normal code snippets except they have a play button.
For editable snippets to work there are a couple more things we need:
- Store the original code in localstorage for editable snippets, we need a way to remember which code belongs to which block
- Have a reset button
- Link in the Ace editor js and css files. I want to only include this if the page actually has a playpen snippet, to reduce load!
- Use the ace editor instead of the
<pre><code>
tags
Most of this should be pretty straightforward, except maybe conditionally include the ace editor if a playpen is detected.
from mdbook.
This sounds pretty great! You should add a quick example to the example docs to show it in practice if you haven't already. I'll have to check it out later.
from mdbook.
You should add a quick example to the example docs to show it in practice if you haven't already.
Yes, the only problem is that I haven't yet built in a way to escape it, soo I can't show how it is done in the docs yet ;)
I will do that now
from mdbook.
Here you go: [Doc - example](http://azerupi.github.io/mdBook/format/rust.html#Inserting runnable Rust files)
from mdbook.
That's so cool!
from mdbook.
@steveklabnik This now offers a hybrid between the book style and the rbe style because of the expansion it allows. For example, here I had to workaround the fact that the example is really huge but the important part is small. The style is to present entire examples so there isn't really a way around it. Compare with say here where the examples are compact but the actually linked to playpen example is basically useless. This would now allow the best of both worlds!
This would be much more useful to the book in general but I could still see it being useful for rbe occasionally. Very cool.
Once it supports ace, I'd start testing porting rbe to see how it works. I'm not sure I'd switch without search but it'd definitely might be worth considering.
from mdbook.
Oh this is amazing. π
from mdbook.
Has there been any change on this? Is there a way to make this editable yet? If it was, I might attempt a big port of rbe next week (no guarantees because I might be busy though). I think this was the major rbe blocker.
from mdbook.
Not really, I have been very busy with school in the last months so I didn't get the chance to work on this project.
I have some experiments in another branch but it doesn't feel right to push all the css and js onto everyone as the majority won't use it. Therefore I wanted to wait until I come up with a plug-in system where you can activate / deactivate features via the configuration file. But this essentially requires a major rewrite. I was poking at it a couple of months back but unfortunately it got sidetracked.
Now that the exam period is over I will hopefully have the time again to make progress on the rewrite.
from mdbook.
Sounds good. FWIW, I think cargo can target a specific branch (or at least a specific revision). So if progress was made to the point where rust editing is pretty decent, we could adopt it. At least, there is that possibility.
from mdbook.
Any updates ?
from mdbook.
I'm not aware of any right now, but I'd like to take a crack at it in the future.
from mdbook.
So, re-reading this issue, it looks like everything but editing has been implemented, right?
from mdbook.
Yes, editing like on rust-by-example requires some heavy-weight javascript and with no easy way to let the user choose what he wants I am not comfortable pushing it onto everyone. #163 would be a big step towards implementing this issue. But it requires a lot of thought and it is probably blocked on other issues.
We could implement a temporary workaround of course, a special option adding all the necessary JS.
from mdbook.
I don't think it's a huge priority; it'd be nice for once we get to RBE, but that's the only thing that supported it, and is not likely to get worked on for a long time.
from mdbook.
Is there something similar for python
from mdbook.
Related Issues (20)
- Verify all Markdown files are linked from SUMMARY.md (or from somewhere else) HOT 1
- Syntax Highlighting for "JSON with Comments" a.k.a. jsonc HOT 1
- Request for Support of .NET 8.0 Features Including Primary Constructors and File-Scoped Namespaces HOT 1
- Bug: separator gets folded by subsection HOT 4
- how to .. localization ? HOT 1
- Summary can't deal with fragments, `#id` style deep links HOT 1
- Advanced features when including files
- markdown > syntax cannot wrap HOT 1
- Links with empty path cause error
- How to prevent the .git directory in the output directory from being deletedοΌ HOT 2
- Let all the output html files share the same one sidebar HOT 6
- Accessibility: New Markdown files must start with Heading Level 2 because Book Title is Heading level 1 HOT 4
- Support '/' shortcut to search
- Images with relative path not displayed on index.html HOT 1
- Figure out a strategy for updating public dependencies HOT 1
- 0.4.38 release has no assets HOT 2
- Is there a way to use own markdown short code templates? HOT 2
- Non-English search support HOT 5
- Replace icon fonts with SVG HOT 1
- Use capital letters to indicate the default value in (y/n) prompts
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
π Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. πππ
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google β€οΈ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from mdbook.