Create project documentation in markdown using `mdbook`

[John15321]

mdBook is a template for creating documentation in markdown. It is mainly used for rust projects, but the template just like markdown itself is language agnostic, it's just a markup language. Start creating documentation for the project using it (in the future it would be accessible by github.io https://github.com/rust-lang/mdBook

[zephaniahong]

@John15321 Hey John! Just want to clarify the difference between this and and writing comments in the code and running cargo doc

Also, do I just create the general structure first or is there already information you would like to be inside?

Thanks!

[John15321]

@John15321 Hey John! Just want to clarify the difference between this and and writing comments in the code and running cargo doc

Also, do I just create the general structure first or is there already information you would like to be inside?

Thanks!

https://youtu.be/tXWscUSYdBs

You can watch the first 17 minutes to get a better understanding.

In short the documentation generated by cargo doc is a so called API documentation or reference documentation or whatever people like to call it. It's minimalistic and purely based on the source code. On the other hand the one by mdbook is meant to be more abstract and fully carted to a human reader. It should perform the role of a usage guide, a guide in general, etc

You can look at the cargo-generate project to get a feel

[zephaniahong]

I'll work on this! Will get it done by this week.

[John15321]

I'll work on this! Will get it done by this week.

Thanks. No rush, its not a race. Noone is trying to chase us with their own rewrite of pip in Rust, the point is to do this right not fast ;)