Add more documentation for Formatters

[benoittgt]

Light documentation for Formatters

At the moment the documentation for Formatters is succint. We should provide more documentation for this part of RSpec.

A good example is this blog post: https://ieftimov.com/how-to-write-rspec-formatters-from-scratch

Maybe we could use "scenarios" to show different way of using the formatter api:

• example_* methods and the output it produce
• order of methods called in the output and what they do. For example dump_failures

Resources

• Existing formater
• https://ieftimov.com/how-to-write-rspec-formatters-from-scratch
• Effective testing with RSpec 3 book and example

[JonRowe]

There is more documentation to be found in http://rspec.info/documentation/3.8/rspec-core/RSpec/Core/Formatters.html and in http://rspec.info/documentation/3.8/rspec-core/RSpec/Core/Formatters/Protocol.html. A lot of which is cribbed across to that blog post.

[benoittgt]

@JonRowe yes 👍 ! Do you think it's enough? Or should we add those links to the relishapp doc?

[JonRowe]

If some one wants to add more scenarios that do interesting things I think I'd be ok with that, but maybe some links to those in the cucumber description would help more :)

[connorshea]

I've been working on a VS Code test explorer extension for Rspec. I'm not getting enough info from the default JSON Formatter, so I've ended up just creating a custom formatter formatter using code from existing formatters and going backward through the rspec-core code to figure out what info was available.

The formatter isn't included in the test explorer yet since I haven't quite gotten it to work how I want. More documentation on building a custom formatter would be a great help :)

[ajn123]

Hi I am new - can I take this issue ?

[JonRowe]

@ajn123 If you feel you can improve the docs I'll certainly take a look

[ajn123]

@JonRowe
Thank you so much, I did a working draft late tonight.

I see the

rake relish[version]  # Push docs/cukes to relishapp using the relish-client-gem
rake relish_staging   # Push to relish staging environment

options, how can I see the relish docs on my computer locally before a pull request ?

[JonRowe]

You'll need to create an account and push your own repo there, see how it's done in the Rakefile

[ajn123]

I see you use:
rake relish[Task]
do you have to put the correct version in it ? I can't seem to get the command recognized.

[benoittgt]

I think you look at this https://github.com/rspec/rspec-core/blob/master/Rakefile#L69-L74 on your own repo. To handle your own repo https://relishapp.com/relish/relish/docs/client-gem/add-a-project. I never did it but I think it should work. Feel free to ping us if you need some help.

[JonRowe]

Yes we put in the correct version, that could be improved I guess! 😂

[JonRowe]

(wrong button clicked, apologies)

[ajn123]

@benoittgt Great thanks!
1 more q: How do I get credentials for staging my own relish app - I see no way to create an account.

[benoittgt]

I think someone with rights (maybe @JonRowe) needs to add you as collaborator. https://relishapp.com/relish/relish/docs/client-gem/add-a-collaborator or you need to contact relishapp to have an account.

I am sorry I never did it. I think you should ask relish for an environment.

[JonRowe]

Er new sign ups appear to be close due to the migration to cucumber.pro, which in turn seems to have been acquired? @mattwynne any advice here?

[mattwynne]

Hey @JonRowe.

We have closed sign-ups to Relish as we no longer want to have to support it.

You're right that [Cucumber Ltd. (which owns both Relish and Jam) has been acquired by SmartBear recently. We are still fully supportive of the RSpec project and community and still have on our roadmap to transition you all over to https://cucumber.io/jam (the new name for Cucumber Pro) as soon as possible. In fact we hope this will be able to happen quicker now that we have more clout behind the development. When we reviewed this a couple of weeks ago, we spotted a couple of features missing from Jam that we think you'd need before you'd be ready to make the jump. @tooky is the person responsible for steering the priorities of Jam, and he's probably best to speak to that in detail.

@ajn123 can you say more about why you need an account on Relish? What were you hoping to do?

[mattwynne]

Ref rspec/rspec-dev#199

[JonRowe]

@mattwynne @ajn123 was hoping to preview documentation changes from this PR

[JonRowe]

Closing due to inactivity and we're migrating to the monorepo, but if people wanted to add more documentation when thats complete there will be plenty of scope to do so!