search

cucumber / gherkin

A parser and compiler for the Gherkin language.
MIT License
161 stars 48 forks source link

Asciidoc Support #10

Open sashokbg opened 1 year ago

sashokbg commented 1 year ago

🤔 What's the problem you're trying to solve?

Feature: Add asciidoc support for feature formatting Asciidoc is a feature rich alternative to markdown that covers almost everything that markdown does but also adds much more

As a product owner I want to use asciidoc formatting for my user stories In order to better express my needs with well-formatted and pretty documents

As a quality engineer I want to write examples (scenarios) using asciidoc So that I can better express the features and underline important information using formatting and images

As a developer I want to receive well-structured user stories to develop So that I know exactly what I need to develop

As an end user I want a pretty and well-formatted living documentation So that I can quickly understand how the software works

As a tech lead I want to generate a website using a tool like antora In order to organize my documentation in a single well-structured documentation site

✨ What's your proposed solution?

There is currently a working markdown format so I think we can base ourselves on this module. I haven't yet looked at the code though ..

⛏ Have you considered any alternatives or workarounds?

There is a project called cukedocktor that I have tried using for a while. Unfortunately this project uses the old version of the cucumber framework pre-ndmessages and lacks some of the newer features of the language like the rules.

It also seems like a redundant solution to the existing react html formatter.

📚 Any additional context?

Thanks for all of the hard work !

This text was originally generated from a template, then edited by hand. You can modify the template here.

sashokbg commented 1 year ago

Hello can anyone please give me some guidelines on where I can start from - I wish to try to implement the ASCIIDOC support :). If I understand correctly I need to implement a Token Matcher just like GherkinInMarkdownTokenMatcher ?

https://github.com/cucumber/common/blob/main/gherkin/javascript/src/GherkinInMarkdownTokenMatcher.ts ?

mattwynne commented 1 year ago

Hey @sashokbg, thanks for pushing on this. It looks to me like you've found the right place in the code to get started. We'll want to see a test-driven solution, so also have a look at https://github.com/cucumber/common/tree/main/gherkin/testdata/ for acceptance tests. We'll also want to add something akin to https://github.com/cucumber/compatibility-kit/tree/main/devkit/samples/markdown so we can test support in the Cucumber implementations themselves.

If you want to chat 🍵 about this, you're welcome to join us in our community Slack in the #committers channel 😄

I'm also available for live pairing ⚡ you can book a slot with me here.

aslakhellesoy commented 1 year ago

Asciidoc is great, but it has lost to Markdown. Very few people use it.

For this reason I'm against adding Asciidoc support. I would rather we focus on improving Markdown support, which is already implemented in the JavaScript implementation of the Gherkin parser, but not yet ported to other languages.

If we haven't (yet) managed to make Markdown supported in all implementations, and also managed to make the community adopt it, why should we start another similar effort for a more obscure markup language?

mpkorstanje commented 1 year ago

Reading this I'm a little confused.

Is the purpose of this request to:

mpkorstanje commented 1 year ago

Also, because I'm doing a clean up of old issues, I'm closing this because I doubt this will happen.

Never the less, please feel free to reopen this discussion.

sashokbg commented 1 year ago

Hello everyone, @mpkorstanje, @aslakhellesoy, @mattwynne

To answer your comments:

I think however that I have a solution that might be good for everyone:

Instead of implementing asciidoc support in the gherkin / common repository we can just add some sort of "CustomFlavorRegistry" that allows us to register any arbitrary type that implements ITokenMatcher.

What we gain:

I wrote some bits of code and can open a draft PR so that we can discuss more details if you wish.

P.S. Please let's keep the conversation productive and not talk about "why that effort" for "that technology that I don't use"

sashokbg commented 1 year ago

I thought i'd give a code example real quick to show how trivial adding "asciidoc" support will become with this new feature:

  1. I modified the original token matcher to accept the prefixes so that we can override them

  2. Implement or extend existing TokenMatcher

    export default class GherkinInAsciidocTokenMatcher extends GherkinInMarkdownTokenMatcher {

constructor(defaultDialectName: string = 'en') {
    const asciidocPrefixes = {
        BULLET: '^(\\s*[*\\.-]\\s*)',
        HEADER: '^(={1,6}\\s)',
    }
    super(defaultDialectName, asciidocPrefixes);
}
}
  3. Then register it
        CustomFlavorRegistry.getInstance().registerFlavor('asciidoc', '.adoc', new GherkinInAsciidocTokenMatcher());
sashokbg commented 1 year ago

PRs opened:

https://github.com/cucumber/gherkin/pull/95 https://github.com/cucumber/messages/pull/139

mpkorstanje commented 1 year ago

I've reopened this issue. It may be a while before we get around to this one though. We're rather short handed at the moment

sashokbg commented 1 year ago

Thank you @mpkorstanje , please don't hesitate to ask me if you need help. I am actually already using the code in the PRs in a forked repo for a project in our company.

I am very passionate about the topic of creating living documentation with asciidoc, antora and cucumber. We can connect on slack / discord if you want to discuss or do pair program.