search

ropensci-archive / reproducibility-guide

:no_entry: ARCHIVED :no_entry:
http://ropensci.github.io/reproducibility-guide/
117 stars 53 forks source link

Possible framework for rendering to html #43

Closed sckott closed 3 years ago

sckott commented 10 years ago

Just saw http://www.gitbook.io/

Looks super simple, and you can make it work with just a few changes I think. ALthough this would be a departure from Jekyll I guess, not sure if you'd want to do that.

karthik commented 10 years ago

Yeah, it's been around for a little while. I don't think it works for more than a few simple use cases. What Martin, Carl and Gavin have worked on is far more sophisticated and would be great once the kinks are sorted out.

iamciera commented 10 years ago

I am open to whatever would allow easiest collaboration and functionality. I think Jekyll is a little hard for people with little HTML knowledge to wrap their heads around at first.

karthik commented 10 years ago

Actually I'm sorry. I was thinking this was an issue in the docs thread. My bad. @sckott is right. Gitbook could be a good option here.

Quick question: What about standard jekyll with a nice template of some sort? That way you can build locally (to test) and GitHub will also build automatically. You can also host this elsewhere if need be.

karthik commented 10 years ago

I think Jekyll is a little hard for people with little HTML knowledge to wrap their heads around at first.

The rOpenSci website runs on Jekyll. It took a little bit of set up to get the templates right but all of the content is written in plain markdown (or .Rmd → .md). That's it. Anyone can contribute a markdown file (either over email or pull request) and you/some other maintainer can build locally and push (or let GitHub build).

cboettig commented 10 years ago

I think this thread highlights some pretty interesting issues visa vi reproducibility, collaboration and technical barriers. On one hand, I agree with Karthik that having good templates in place in Jekyll can alleviate some of the barriers of CSS & HTML. (e.g. Jekyll bootstraphttp://jekyllbootstrap.com/is one example allowing users to interactively select themes rather than ever look at an HTML block.) While I agree that Jekyll is still a rough learning curve, I think good templates, plugins, etc could alleviate a lot of the pain.

On the other hand, I suspect some tradeoff between functionality and ease is inevitable, not just in the web aspect but throughout the tools discussed in this project.

For instance, markdown might be a perfect example of where this balance is met: offering much of the power functionality of HTML or LaTeX but having an ease of use closer to but still far less familiar then MS Word. Knowing where the right balance is for a publishing platform (Jekyll? gitbook? something else?) probably depends on (A) what elements are core features vs what we can do without, and (B) what skills or background are reasonable to assume and what crosses the line of too technical.

On Tue, Apr 15, 2014 at 1:07 PM, Karthik Ram notifications@github.comwrote:

I think Jekyll is a little hard for people with little HTML knowledge to wrap their heads around at first.

The rOpenSci website runs on Jekyll. It took a little bit of set up to get the templates right but all of the content is written in plain markdown (or .Rmd → .md). That's it. Anyone can contribute a markdown file (either over email or pull request) and you/some other maintainer can build locally and push (or let GitHub build).

— Reply to this email directly or view it on GitHubhttps://github.com/ropensci/reproducibility-guide/issues/43#issuecomment-40527676 .

Carl Boettiger UC Santa Cruz http://carlboettiger.info/

iamciera commented 10 years ago

Let's stay with Jekyll at the moment, but I will keep these issues in mind.

szeitlin commented 10 years ago

I'm playing around with github.io and markdown right now. I got a draft up, but I can't figure out how to incorporate changes, since it seems to have given me back pure html. I don't see how to get github to build my markdown file? Help-?

I'm curious to know whether Jeckyll will be easier in the sense that the drag of editing this stuff is the workflow cycle of writing -> viewing --> revising -> viewing. It has to be easy and fast. Since Ciera already built the templates and all we have to do is provide the markdown, that's pretty easy!

Maybe we should consider longer-term maintenance, and ultimately the lifetime of these options - are we going to have Ciera around forever to help with this? Or is it already simple enough to be relatively self-sustaining?

iamciera commented 10 years ago

I think these are all super valid concerns. I checked out http://www.gitbook.io/ and it does look promising. I am a little apprehensive to downloading a GUI to make changes/write to the book, but maybe there is another way around that (?)

Does anyone know of a good example of a similar functioning project that employs a different and more effective strategy for collaboration of writing and display of that writing on Github?

szeitlin commented 10 years ago

Someone mentioned something to me recently, I will have to ask him since I don't think I wrote down the name. It might have been an experimental plugin to google docs-?

Found the markdown info I was looking for, which I think (?) will help with some of the issues I was having: https://help.github.com/articles/github-flavored-markdown

rahul286 commented 9 years ago

@iamciera gitbook supports github repos now. I am not sure if it used to support Github back then.

Their own docs are hosted on Github now https://github.com/GitbookIO/documentation/