search

tokio-rs / doc-push

Tokio doc blitz effort - A concerted effort to improve Tokio's documentation.
MIT License
50 stars 7 forks source link

Initial skeleton of the cookbook in mdbook format #63

Open eminence opened 6 years ago

eminence commented 6 years ago

This creates an initial skeleton of the cookbook in mdbook format (the same format used by the rust cookbook).

The only content here is a copy of cookbook.md, but split up into multiple files. Hopefully this layout matches what you had in mind for the cookbook.

Preview of the rendered book

rylev commented 6 years ago

What are your thoughts on the advantages of having this as a separate book vs just having it as a new section in the existing guides?

eminence commented 6 years ago

This comment which references the rust cookbook made me think that an mdBook was the target format. But if that's not the case, then we can simply drop this PR. On the other hand, if we want mdBook for everything (not just the cookbook), then I can easily modify the structure to bring everything under the mdBook structure.

AndyGauge commented 6 years ago

mdbook provides links to run in the browser, expand hidden lines, and is backed by rust-skeptic. It looks like your ci is integrated with tests, but I'm not sure how convenient they are running locally.

carllerche commented 6 years ago

Ah, I was only referencing the rough structure (one page per category and many examples per page).

If mdBook can be made to integrate into the Tokio website's layout and CSS (https://tokio.rs), then I would be fine wity replacing the docs section entirely with mdBook.

My primary goal is to maintain a cohesive website feel.

carllerche commented 6 years ago

That said, the sketch looks good at a glance 👍

carllerche commented 6 years ago

@AndyGauge @eminence if you want, someone can open an issue here to discuss mdBook for the website.

eminence commented 6 years ago

let me take a stab at bringing in the tokio website style into this book skeleton to see how that looks. then we can see how to move forward from there.