Migrate documentation from Relishapp to Github page

[benoittgt]

Recently Relishapp was sadly broken. It is not possible to make it easily work again.

To let user access to a new documentation I tried to migrate all documentation to Github page.
Tasks done in this PR:

• Generate markdown from .feature file using https://github.com/raviqqe/gherkin2markdown
• Serve them using docsify
• Properly generate sidebar with a custom script
• Provide a script to easily generate documentation
• Reformat some part of the features files for better display in markdown format

A demo with this code can be seen here: https://benoittgt.github.io/vcr/#/

There is still tasks that should be addressed. See list here: #967 (comment). But I think we should already offer a documentation.

Sorry for the not super well commit story.

Close: #967

[Fryguy]

These look beautiful. Thank you for taking this on.

[benoittgt]

We will have to change link in command output too.

[olleolleolle]

We will have to change link in command output too.

Right, these:

vcr/lib/vcr/errors.rb

Line 198 in 5c0ded8

"https://www.relishapp.com/vcr/vcr/v/%s/docs/record-modes/new-episodes"

With a link like

https://benoittgt.github.io/vcr/#/record_modes/new_episodes?id=new_episodes

...since I can't seem to locate any "version-specific docs" link there.

[benoittgt]

I need to do extra work for the version. I will see what I can do.

[olleolleolle]

@benoittgt At any rate, people will have to upgrade to new code to enjoy the new links, anyway, so no rush.

[olleolleolle]

@benoittgt As an update, I have merged #973 which uses the benoittgt GitHub Pages site for docs, in the RubyGems metadata section for homepage, which will be reflected on that site with the next release.

[benoittgt]

Ok thanks ! To accept this current PR we want to have the version switcher? Anything else? :)

[olleolleolle]

@benoittgt I think we are amazing if we have a version switcher.

[jmpage]

@olleolleolle I'm sorry to jump in out of the blue, but would this be worth merging on the basis of "perfect is the enemy of done," after which a version switcher could be added?

I have personally found the new documentation site to be very helpful, especially compared to the unfortunately dead relishapp docs.

[benoittgt]

For the version switcher. There is a nice proposal on this repository with the result.

It is a little bit detailed in an article.

I started looking at it, but it requires some work. And probably we need to create "stable" branch OR limit the documentation per tag. If we want something more dynamic, we need to follow imgproxy code.

[olleolleolle]

@benoittgt ❤️❤️❤️ That's fantastic!

[olleolleolle]

@benoittgt I dropped Ruby 2.6 from CI and gemspec, now, so if you rebase, we ought to be green.

[olleolleolle]

https://github.com/vcr/vcr/blob/master/Rakefile#L33 This code still exists, and I guess could get some automation love.

@benoittgt None of those scripts are in use, right? I ought to be able to remove them, no replacement.

EDIT: Update - we no longer have those Rake tasks or Relish app code around.