Move manual to its own repo

[PragTob]

(moved/adapted from shoes/shoesrb.com#46 for better visibility)

Right now the shoesrb website basically is HTML generated from the manual markdown file in the shoesrb.com repository. The real source file for the manual is in the shoes repository and in the shoes4 repository (manual-en.txt). The markdown files are used for our built in manual there.

I would want to have this all in one place and then the others just use that one file so that they do not get out of sync. E.g. I don't want someone to change something in the HTML at shoesrb.com that is not propagated back to the original markdown. Also the other way around, an update to the manual in the shoes4 repository should show up on the shoesrb.com home page.

We could just manually copy it over every once in a while (from a manual repository) but maybe a gem would be better, because you know GEMIFY ALL THE THINGS - so we could serve that as a gem for shoes4/3 (or maybe we just leave 3 alone) and have it as a dependency. The website should be able to just use the markdown. Right now the manual is just one gigantic file so it might be good to split that up to multiple files (according to sub pages), as I dunno if jekyll can handle that one big markdown file the way we want it to handle (with subpages). So either multiple files (should work) or we build a rake task that compiles the HTML files.

We can't just use the gem for the web page, because with github pages we can't use pages afaik :(

Either way, having a central manual authority would be really neat and important!

So yeah what do you think about that?

Cheers,
Tobi

cc: #731

[wasnotrice]

I agree, it would be great to have the manual be easy to edit and
regenerate, and to keep in sync. Good idea!

On Sun, Jun 1, 2014 at 4:24 AM, Tobias Pfeiffer notifications@github.com
wrote:

(moved/adapted from shoes/shoesrb.com#46
shoes/shoesrb.com#46 for better visibility)

Right now the shoesrb website basically is HTML generated from the manual
markdown file in the shoesrb.com repository. The real source file for the
manual is in the shoes repository and in the shoes4 repository (
manual-en.txt
https://github.com/shoes/shoes4/blob/master/static/manual-en.txt). The
markdown files are used for our built in manual there.

I would want to have this all in one place and then the others just use
that one file so that they do not get out of sync. E.g. I don't want
someone to change something in the HTML at shoesrb.com that is not
propagated back to the original markdown. Also the other way around, an
update to the manual in the shoes4 repository should show up on the
shoesrb.com home page.

We could just manually copy it over every once in a while (from a manual
repository) but maybe a gem would be better, because you know GEMIFY ALL
THE THINGS - so we could serve that as a gem for shoes4/3 (or maybe we just
leave 3 alone) and have it as a dependency. The website should be able to
just use the markdown. Right now the manual is just one gigantic file so it
might be good to split that up to multiple files (according to sub pages),
as I dunno if jekyll can handle that one big markdown file the way we want
it to handle (with subpages). So either multiple files (should work) or we
build a rake task that compiles the HTML files.

We can't just use the gem for the web page, because with github pages we
can't use pages afaik :(

Either way, having a central manual authority would be really neat and
important!

So yeah what do you think about that?

Cheers,
Tobi

cc: #731 #731

—
Reply to this email directly or view it on GitHub
#745.

[jasonrclark]

Agreed, and absolutely think the manual deserves a lot of love and care before the full 4.0 release, so this would be a good step in making that easier to do.

[PragTob]

While we restructure our gem structure (#931) and extracted shoes-highlighter this might be worthwhile to tackle soon as well.

What do you think?

[jasonrclark]

Seems reasonable to me. Will consider picking this up as I'm doing my gem shuffling (hopefully this weekend, or next week as I'm traveling around RubyConf!)

[PragTob]

👏 @jasonrclark