Skip to content

Conversation

@deesh-code
Copy link
Contributor

Here's what I accomplished:

Changes Made

 1. Removed Standalone HTML Files: 
   * Deleted docs/grammar_railroad_core.html
    
   * Deleted docs/grammar_railroad_full.html 
    
   * Deleted docs/README_grammar.md
 2. Integrated into Sphinx Documentation:
   * Created readthedocs/grammar.md with comprehensive MyST markdown documentation
    
   * Updated readthedocs/index.md to include "Grammar Reference" in the table of contents
    
   * The grammar documentation is now part of the main Sphinx-based user documentation system
 3. Updated Generator Script:
   * Modified scripts/generate_railroad_diagrams.py to generate MyST markdown instead of HTML
    
   * Script now creates documentation that integrates seamlessly with the Sphinx system
    
   * Kept the EBNF file generation for users who want to use external tools
 4. Maintained External Tool Support:
   * Kept docs/grammar.ebnf file for users who want to use https://www.bottlecaps.de/rr/ui 

(https://www.bottlecaps.de/rr/ui)

   * Users can copy the EBNF grammar and paste it into external railroad diagram generators

Key Features of the New Implementation

 * Sphinx Integration: Grammar documentation is now part of the main readthedocs system
 * MyST Markdown: Uses the same format as other documentation files
 * Comprehensive Coverage: Includes both core Datalog and extended Mangle grammar
 * Rich Examples: Provides practical code examples for each grammar construct
 * Easy Maintenance: Single source of truth that can be regenerated from the ANTLR grammar
 * External Tool Support: Users can still use bottlecaps.de for interactive railroad diagrams

deesh-code and others added 2 commits October 11, 2025 17:21
- Create script to generate railroad diagrams from ANTLR grammar
- Generate core Datalog grammar focused on essential constructs
- Generate complete Mangle grammar with all language features
- Create interactive HTML files with copy-to-clipboard functionality
- Add EBNF grammar file for external tools
- Include comprehensive documentation

Files added:
- scripts/generate_railroad_diagrams.py - Generator script
- docs/grammar_railroad_core.html - Core Datalog railroad diagrams
- docs/grammar_railroad_full.html - Complete grammar railroad diagrams
- docs/grammar.ebnf - EBNF grammar for external tools
- docs/README_grammar.md - Documentation and usage guide

Addresses GitHub issue #3 with railroad diagrams as requested by mingodad
and suggestions from burakemir for core Datalog syntax focus.
Addresses feedback from @burakemir in PR #76:
- Remove standalone HTML files from docs/ directory
- Add grammar reference to readthedocs/ using MyST markdown
- Update index.md to include Grammar Reference section
- Modify generator script to create Sphinx-compatible documentation
- Keep EBNF file in docs/ for external railroad diagram tools

This provides comprehensive grammar documentation within the existing
Sphinx documentation system rather than external HTML pages.
@google-cla
Copy link

google-cla bot commented Oct 15, 2025

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

@deesh-code
Copy link
Contributor Author

Is anyone here to review

@burakemir
Copy link
Collaborator

Hey there, I was waiting for you to sign the CLA.

@deesh-code deesh-code closed this Oct 30, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants