aboutcode-org / aboutcode-org/pygmars

Suggestion: Improve documentation with a "Getting Started" guide

Abierto
#16 0 comentarios 0 reacciones 0 asignados Ver en GitHub
Lenguaje dominante
Python
Estrellas
6
Forks
4
Métricas de merge de PR
Sin PR fusionados en 30 d

Descripción

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!

Guía de contribución

No hay ninguna guía de contribución indexada para este repositorio

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.