Documentation generator for LALRPOP ( markdown, railroad diagram svg, ebnf ) #658
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Signed-off-by: Darach Ennis <darach@gmail.com>
|
Here's a repo with the example |
|
Nods to @brendanzab - liking fathom 👀 👍 |
Signed-off-by: Darach Ennis <darach@gmail.com>
Signed-off-by: Darach Ennis <darach@gmail.com>
Signed-off-by: Darach Ennis <darach@gmail.com>
Signed-off-by: Darach Ennis <darach@gmail.com>
Heh, glad you are enjoying it! Just a heads up that the active repo is at yeslogic/fathom 😊 |
Signed-off-by: Darach Ennis <darach@gmail.com>
Signed-off-by: Darach Ennis <darach@gmail.com>
|
This has worked well for documentation on the current release of tremor. The full generated docset for the tremor lalrpop grammar is now live here deployed with docusaurus v2 beta. |
darach
changed the title
Signed-off-by: Heinz N. Gies <heinz@licenser.net>
Signed-off-by: Heinz N. Gies <heinz@licenser.net>
Signed-off-by: Darach Ennis <darach@gmail.com>
Make image markup in generated markup support a switchable style
Use markdown images by default with switchable alternative back to html `img` tags
|
👋 Wondering if this branch is ok to merge or if there are related docs changes desireable for completeness. We've had no issues in our CI/CD system with this to date. Please let us know if there's anything we can/should clean up! |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
We use LALRPOP on the tremor project for
defining the grammar of our embedded DSLs. Up until the current release, we have been maintaining
a proximate EBNF file and using online railroad diagram generators to assist with our language reference.
This has proven cumbersome, error prone and high maintenance!
This PR is a work in progress extension to LALRPOP that derives EBNF from the LALRPOP grammar, generates
railroad diagrams with support for LALRPOP macro rules visually, and generates markdown for the grammar
that is compatible with github markdown, pandoc, docusaurus.
The markdown can be annotated with human-maintained markdown files.
A few small changes to the core
lalrpoppackage is needed to expose the parse tree such thatthe grammar can be visited. If changes come to mind to align it better with the other LALRPOP crates
happy to make any such changes.
The same pic-args, session, config and api pattern was used with the
lalrpop-docgentool but thistool hasn't yet been tested with or integrated with
build.rsstyle usage.Signed-off-by: Darach Ennis darach@gmail.com