New Documentation Website

[krainboltgreene]

#712 #304 #17 #694 #525

AKA "Relish is dead, what now?"

Apparently they have a new site called https://cucumber.io/jam.

[andrewmcodes]

@krainboltgreene you could use a gem to convert the cucumber files to markdown and then use something like gitbook or roll a site with Gatsby or Jekyll. I’d be happy to help with this.

[krainboltgreene]

I've used gitbook extensively in the past, I like them well enough. Sure, if you're willing to devote time to it then make the PR, you'll get my primary attention.

[olleolleolle]

Going to try a few tools, see what they're made of.

http://www.picklesdoc.com/ for example. (I learned: It's a Windows tool, and I don't run that.)

[andrewmcodes]

I used this tool to see the type of markup it would produce and here is an example of 5.0 docs on gitbook. I noticed it strips the language tags from code blocks, omits sections that use @exclude-foo, and a few indentation issues. @krainboltgreene if you think it’s fine, I can port over all the docs and discuss how to automate or explore another tool. I really don’t want to write my own conversion gem unless I have to but I am personally not a fan of the output. I have looked at other tools and haven’t found a good alternative and wasn’t successful at my first attempt to create a conversion gem 🙄

[olleolleolle]

Blog post we could link to: https://fabioperrella.github.io/10_tips_to_help_using_the_VCR_gem_in_your_ruby_test_suite.html

[dgarwood]

@andrewmcodes @krainboltgreene appears their Jam got canned as well: https://smartbear.com/blog/test-and-monitor/smartbear-acquires-cucumber/

looks like this hasn't been updated in a while. I wasn't able to view the example on gitbook. Is there anything I can do to help?

[olleolleolle]

Any research about how to create Relish-like output are interesting to this Issue.

@andrewmcodes This is what the gitbook link looked like on logging in:

✨

[nicolasiensen]

I decided to give it a try using gherkin2markdown and GitBook, just like @andrewmcodes suggested.

I tried to keep the same structure as we have in Relishapp, but I didn't create all the pages as my goal here is to have a proof of concept.

I imported all the pages manually, but I'm pretty sure we could automate this process if we decide to go with this solution.

The pages from Getting Started to Contributing are all markdown files contained in the source code of the project. The pages under the Test Frameworks section were transformed by gherkin2markdown and then imported to GitBook.

Let me know what you think.

https://nicolasiensen.gitbook.io/vcr-documentation/

[olleolleolle]

It looks like a good start.

Thanks for taking this up, @nicolasiensen!

An enjoyable presentation.

(After this line, nonproductive bike-shedding! 😄 )

---

Some (future) polishing for readability would make things shinier (syntax highlighting).
Some typography tweaks like in the Relish example below:

What I like: the structure is strongly presented with some justification/whitespace.

[nicolasiensen]

I gave it another try using a much less manual approach:

We add a SUMMARY.md file in the root folder of the repository containing the structure of the VCR documentation, as documented by GitBook.

You can check how the codebase would look like on this branch.

Following this approach, we would need to include the markdown version of the feature files as part of the codebase 🙁.

@olleolleolle I didn't tackle the feedback you provided above just yet.

Not much has changed from the previous trial, but here is how the documentation looks like https://nicolasiensen.gitbook.io/vcr

[nicolasiensen]

I've worked a bit more on it today, and I managed to add GitBook variants to account for different versions of the library:

We can setup GitBook to create one variant of the documentation per branch. Unfortunately, it doesn't work with git tags.

We can specify the branches we want GitBook to create documentation variants. I configured it to catch all branches matching the pattern v-*.

I created two branches on my fork derived from their respective tags:

• https://github.com/nicolasiensen/vcr/tree/v-6.0.0
• https://github.com/nicolasiensen/vcr/tree/v-5.1.0

I pushed to each branch the files necessary to integrate with GitBook and voilà.

I have to say that it would be quite some work to set up the documentation for each version of the library, but it is possible to do it.

I have also completed the documentation, so it has all the sections we currently have in Relishapp.

You can check the documentation in the following link:

https://nicolasiensen.gitbook.io/vcr/

[nicolasiensen]

I was reading about what the folks from RSpec are planning to do regarding the discontinuation of Relish, and it seems that they are planning to migrate their documentation to Cucumber Pro: rspec/rspec-dev#199.

GitBook is cool, but the Gherkin documentation would never look as gorgeous as if we host it in a platform built for that purpose. Also, the tooling around the project to transform Gherkin files into Markdown would add an extra load to the project ecosystem that I'm not a big fan of.

All in all, I would wait to see what Cucumber Pro is going to turn into. It looks like Relish will stay around as long as Cucumber Pro is not ready for RSpec.

What do you think?

[olleolleolle]

Looks like Jam, aka Cucumber Pro, is a ways off in the future.

[andrewmcodes]

I totally let this slip off my radar after changing teams. Unfortunately I just don't have the bandwidth to pick it back up. Glad to see some folks were able to step up 🙏

[nicolasiensen]

I have set the GitBook project aside for a bit to explore how we could leverage our existing YARD documentation to include the Cucumber features.

I found a project called yard-cucumber, which is not very active but does a fair job transforming each feature file into a YARD documentation page and indexing it to be searchable.

This way, we centralize the documentation of the library into one single place while we stay away from the extra tooling that GitBook requires.

You can have a sneak peek of the result below:

There is certainly room for improvement, but I wanted to hear what you think about this approach before investing more time on it.

[olleolleolle]

Possibility: YARD-generated HTML could be served as GitHub Pages content. yard-cucumber looks very strong within the constraints given.