Using YARD to document feature specs (question)

[vizcay]

I'm looking to create a tool to auto-generate documentation of the features of an application parsing spec/feature. I've come across yard, and I'm analyzing it as an option to mount on it's architecture in the form of a plugin, but not 100% sure because maybe it's simpler to try to custom parse the rspec files myself by means of regex (of course it will not be a complete parser, but just enough to work).

My ideal output will be,

• Add a section in the caegories of the left (among Classes, Methods, etc) as "Features". For every "Rspec.feature XXX" there should be an entry there.
• The document for every feature should have an structure that resembles the spec (context, it, etc) and it should be possible to expand it to see the source.
• The comments before the context, it blocks should be integrated into the document, here we plan to land the "uses cases" of the application.
• It should be possible to link from other sections to those specifications.

The other option I'm evaluating is to use a custom parser and generate directly markdown powered by a wiki engine like gollum. ¿It's feasible to do what I want? ¿How much work do you think it will take? I've read the README and the docs of yard, but not sure about the work involved because I haven't dived into the code.

[lsegal]

maybe it's simpler to try to custom parse the rspec files myself by means of regex

It's not simpler.

I'm looking to create a tool to auto-generate documentation of the features of an application parsing spec/feature.

https://github.com/burtlo/yard-rspec

[emiltin]

hi @vizcay did you get any further with this? I'm trying to do same, see #1368

[vizcay]

hi @vizcay did you get any further with this? I'm trying to do same, see #1368

Hi @emiltin IIRC I've tried a little but it wasn't easy to extend YARD in a way to accomplish this. I think that starting a fresh project will be easier unfortunately.

[emiltin]

Hi @vizcay thank you for you comment. Did you find some things were not possible using the extensions mechanism, or did you lack documentation of how to do it?

I hope the maintainers can provide som input on whether it is possible to document rspec tests with Yard, and if so how.

[lsegal]

I hope the maintainers can provide some input on whether it is possible to document rspec tests with Yard

This was already asked and answered in this issue above, see here. There are a few existing plugins that parse rspec already; if you're looking to add or improve support you can contribute to or fork those projects.

[emiltin]

Thank you @lsegal.

yard-rspec seems stale. The readme states that it's in development and not useful yet, but the latest commit is more than 10 years old. I cannot get it to generate any output.

I also found https://github.com/lsegal/yard-spec-plugin, but the latest commit is from 2010, and when I try it nothing is generated.

Do you know of any working examples of parsing rspec?

[emiltin]

I'm opening some issues in https://github.com/lsegal/yard-spec-plugin to try to understand how to make it work for my use case, which is very simple: rspec it() blocks documented with comments.