New Documentation Website #856
Replies: 18 comments 1 reply
-
@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. |
Beta Was this translation helpful? Give feedback.
-
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. |
Beta Was this translation helpful? Give feedback.
-
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.) |
Beta Was this translation helpful? Give feedback.
-
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 |
Beta Was this translation helpful? Give feedback.
-
Blog post we could link to: https://fabioperrella.github.io/10_tips_to_help_using_the_VCR_gem_in_your_ruby_test_suite.html |
Beta Was this translation helpful? Give feedback.
-
@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? |
Beta Was this translation helpful? Give feedback.
-
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: ✨ |
Beta Was this translation helpful? Give feedback.
-
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. |
Beta Was this translation helpful? Give feedback.
-
It looks like a good start. Thanks for taking this up, @nicolasiensen! An enjoyable presentation. (After this line, nonproductive bike-shedding! 😄 ) |
Beta Was this translation helpful? Give feedback.
-
I gave it another try using a much less manual approach: We add a 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 |
Beta Was this translation helpful? Give feedback.
-
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 I created two branches on my fork derived from their respective tags:
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: |
Beta Was this translation helpful? Give feedback.
-
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? |
Beta Was this translation helpful? Give feedback.
-
Looks like Jam, aka Cucumber Pro, is a ways off in the future. |
Beta Was this translation helpful? Give feedback.
-
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 🙏 |
Beta Was this translation helpful? Give feedback.
-
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 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. |
Beta Was this translation helpful? Give feedback.
-
Possibility: YARD-generated HTML could be served as GitHub Pages content. |
Beta Was this translation helpful? Give feedback.
-
To get close to what we had on Relish, perhaps we can use the cucumber HTML presenter:
|
Beta Was this translation helpful? Give feedback.
-
Folks, I just wanted to add a bit of perspective to this from the "inside" of Cucumber/SmartBear. We've very much committed to supporting open source BDD teams publish their living documentation, and I'm sorry we haven't yet managed to achieve feature parity in the regard with Relish on any of the other attempts we've made to solve this problem (Cucumber Pro, Jam, Cucumber Reports, and CucumberStudio). We have stopped allowing sign-ups on https://relishapp.com as we don't see a commercial future for the project/codebase, and don't want to burn hours on support and maintenance, but we'll keep it up and running to host RSpec, VCR and other public projects' docs as long as there isn't a better alternative. If an open source project like this one needs users to have access, we can still do that from the Rails console, so just let me know. Consider yourselves as having VIP level support status 😁 I'll cc @cbliard and @tooky here who are in charge of the priorities for https://reports.cucumber.io and https://studio.cucumber.io and can bear this need in mind as they're making plans. |
Beta Was this translation helpful? Give feedback.
-
#712 #304 #17 #694 #525
AKA "Relish is dead, what now?"
Apparently they have a new site called https://cucumber.io/jam.
Beta Was this translation helpful? Give feedback.
All reactions