Suggestion: Improve documentation with a "Getting Started" guide #16
Description
I've been trying out pygmars and I really like it. It's fast and simple - exactly what I needed for lightweight parsing tasks. The fact that it has no dependencies and just works is a breath of fresh air compared to heavier alternatives.
While the README does a great job explaining the "why" and theory behind pygmars, I think it could be even better with a practical "Getting Started" guide to help new users hit the ground running.
Specifically, it would be helpful to add:
- Installation -
pip install pygmars(simple, but worth mentioning) - Core concepts with minimal code examples:
- What are Tokens?
- How to create a Lexer with regex patterns
- How to define Grammar rules
- How to use the Parser and get a Tree
- A complete, runnable example from start to finish
- Note about Pygments integration for programming language parsing
Helpful Reference
I found these community-generated pages that demonstrate the kind of practical guide I'm thinking of:
- https://deepwiki.com/aboutcode-org/pygmars
- https://deepwiki.com/search/how-to-start-with-pygmars_c764102e-594f-4fb4-b11d-9bc78f474ac2?mode=fast
They pull working examples from the test suite and present them in a beginner-friendly way. Something similar in the official docs would make pygmars even more accessible.
Why This Matters?
The library is already great - fast, simple, no bloat. Better onboarding docs would just help more people discover that and start using it.
Quick question
I noticed the docs/source/ folder has some .rst files, but I don't see the documentation hosted anywhere publicly. Just curious:
- Are there plans to host the docs on ReadTheDocs or similar?
- Is the current structure actively used / something you want to keep?
I'm happy to help
If this sounds good, I'd be glad to submit a PR with these documentation improvements. Just let me know if you'd like that and if there's any specific style/format you prefer.
Thanks for creating and maintaining pygmars!