Requirements-as-code using Gherkin: Literate-wordle

[OverkillGuy]

Hello! I'm Jb, long time fan of requirements-as-code, I keep pushing all my dev colleagues to ditch Word for docs-as-code.

I want to showcase a pet project that occupied my past few months, and while not directly about requirements, features them heavily.

Literate programming Wordle implementation

• Announcement blogpost
• Project Docs/Homepage
• Actual literate programming implementation aka "the novel"
• Generated requirements page matching Gherkin features/ folder
• Github repo

The idea was to showcase the software development process using BDD/TDD, with Gherkin for requirements gathering. I wanted to demonstrate what I wrote over multiple previous blog posts, using modern Python. I chose Wordle as topic, because it is simple enough to implement, but also needs a couple tricks of design to actually work. The need to narrate the development process led me to use literate programming for spinning a story around code being built.

The particular contribution of sphinx-needs was exporting each gherkin file under the features/ folder as requirements. The file tracking was done in the conf.py, homebrewed, with the sister package "sphinx-collections" transforming files detected into jinja2 template expansion of the form:

.. req:: {{feature.filename}}
   :id: FEATURE_{{feature.filename | replace(".feature", "") | upper }}

   .. literalinclude:: gherkin_features/{{feature.filename}}
      :language: gherkin
      :caption: Rendered from file `features/{{feature.filename}}`

e.g.

.. req:: command_line_entrypoint.feature
   :id: FEATURE_COMMAND_LINE_ENTRYPOINT

   .. literalinclude:: gherkin_features/command_line_entrypoint.feature
      :language: gherkin
      :caption: Rendered from file `features/command_line_entrypoint.feature`

So the requirement object contains the code snippets themselves, and all this is automatic (any new file in the right folder would automatically expand into new requirement for that page). See the resulting requirements page matching Gherkin features/ folder.

So, yeah, I got the opportunity to showcase a creative way to bring together requirements-as-code (via sphinx-needs), and Gherkin/BDD, which was tons of fun to me.

Thanks again @danwos for releasing the package, and to useblocks as a whole.
I hope this minor "success story" of mine can help this project get the popularity it deserves.

[danwos]

Hi Jb,
thanks for sharing this awesome project and the documentation with us. 👍
I'm not done with reading everything you have documented, but I already love it, especially as it covers also BDD. A topic in which I'm always interested but never had the chance to test in a real project.

Would it be okay for you to have 1-2 links to your project in our documentation?
I have always planned to have a page for external links. For blogs, tutorials, example implementation, ...
But I never had the right targets. Yours would be perfect :)

Thanks again for sharing this. I may come back to this after I had the chance to test your approach with Gherkin.
I love the way you have combined and automated everything.

[OverkillGuy]

Happy you like it!

Fine by me to get a few links: I'd love the publicity, and showing sphinx-needs is mature via examples is cool.

I didn't stress it that much on the post itself, but if you like BDD, I think you'll enjoy the blogposts I wrote about it, of which this wordle codebase is a sort of demo for:

• Gherkin Features for user requirements (1/3)
• BDD Dreams, Cucumber And Gherkin (2/3)
• Low-tech Cucumber replacement (3/3)

Overall this is the first time I get to demo this cucumber approach in public, as I was growing this at work, but with 0 publication opportunity. Now this is finally public, I'm toying with toolchain integration, especially in docs, as you saw.

I'm still evolving the comments-based "low tech cucumber" of the third article, in particular building a new tool, something I'm calling grepkin (Grep for Gherkin). I'll report about it in a blogpost once it reaches some usefulness.