WIP mdBook

[teonbrooks]

closes #18. here's a proof of concept of mdBook rendered here.

[teonbrooks]

cc: @chrisfilo

[chrisgorgo]

That's an awesome proof of concept. Thanks for sharing.

@choldgraf do you have some experience with such solutions? WDYT?

[choldgraf]

very cool! the general layout is very similar to what we've been doing w/ Jekyll textbooks (here's an example texbook: https://www.textbook.ds100.org/)

I'm +0 on choosing a specific build system.

On the one hand, mdbook has first class support for "book" structures. On the other, it uses Rust which is an awesome tool/community, but is very unfamiliar to the scientific analytics community.

On the one hand, Jekyll is fairly familiar and has first-class github support, on the other, it's not "designed" to host books etc.

One potential difference is the templating engine used under the hood...does mdbooks use liquid?

[choldgraf]

also @teonbrooks - what's the closest "standard" license to the mozilla public license? Is it basically MIT?

[chrisgorgo]

It uses handlebars for templating - see https://rust-lang-nursery.github.io/mdBook/format/theme/index.html for details.

I think we should move fast with splitting the document and adopting a framework (we already have people sending content based PRs). mdbook seems to be easy to implement - are there any red flags?

[teonbrooks]

also @teonbrooks - what's the closest "standard" license to the mozilla public license? Is it basically MIT?

I think the closest would be in fact MIT but don't quite. MPL is a very permissive license from my understanding.

[teonbrooks]

I think we should move fast with splitting the document and adopting a framework (we already have people sending content based PRs). mdbook seems to be easy to implement - are there any red flags?

I agree. I think it would make build a static site easy and it would make diffing even easier and clearer.

[choldgraf]

as long as MPL is basically MIT, then I'm +1 on mdbook. My biggest concern is maintainability from a community that mostly doesn't use Rust, but if the templating is straightforward then I'm happy w/ it

[teonbrooks]

found this blogpost about the MPL license.

tl;dr: all the things outside of the mdBook project can be whatever license we select (MIT CC-BY likely). if we modify the source code of mdBook, then the changes go back to the project under the MPL. it's seen as win-win for everyone 🎉

[choldgraf]

@teonbrooks one thing I think we should do if we use mdBook is write up some dev docs so that others in the community know how the general build system works. Does that sound reasonable?

[teonbrooks]

@choldgraf yes, agreed. I think we should make it a separate PR bc I think the restructuring from the monolithic specification to sections should happen soon especially since people are turning their eyes to the repo

[chrisgorgo]

+1 also #18 (comment)

[choldgraf]

+1 on a separate PR.

[teonbrooks]

closing this pr for now to hash out discussion on #18. we've separated out the md splitting (#28) from the rendering engine

[teonbrooks]

we can re-open this if we decide to go the way of mdBook