aboutcode-org / aboutcode-org/pygmars

Suggestion: Improve documentation with a "Getting Started" guide

Aperta
#16 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
Lingua principale
Python
Stelle
6
Fork
4
Metriche di merge delle PR
Nessuna PR unita negli ultimi 30g

Descrizione

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:

1. **Installation** - `pip install pygmars` (simple, but worth mentioning)
2. **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
3. **A complete, runnable example** from start to finish
4. **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!

Guida per i contributori

Nessuna guida per i contributori indicizzata per questo repository

Valutazione

Questa issue non è ancora stata valutata.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.