Improve documentation

[ketkarameya]

Currently we maintain all our documentation in the two READMEs - README and POLYGLOT_README.
This makes our documentation a bit confusing and a bit intimidating. At some level, I feel it might be hard for a random developer to understand the purpose of this project.
At a higher level my idea is :

1. Merge README and POLYGLOT_README
2. Leverage the Github Wikis for our long form write up around how to use polyglot piranha.

As per good practices - A README file quickly tells what your project can do, while you can use a wiki to provide additional documentation. In contrast our POLYGLOT_README is too detailed. I feel having one huge file makes it difficult to navigate too (while reading). Also there is that intimidating rule graph diagram at the beginning.

My plan is to move the following sections to wiki :

1. Stale Feature Flag Cleanup in Depth
2. Visualizing Graphs for Rules and Groups
3. Piranha Arguments
4. Update the CONTRIBUTING.md (edit)

[lazaroclapp]

Agreed here. README should have enough information to get a user started with using PolyglotPiranha for a basic use case, with the Wiki providing more detailed info divided into sections which can be explored somewhat out of order. Since you are doing this, I'll also point out the CONTRIBUTING.md file might need some minor updates, e.g. it still gives Java and ObjC formatters as examples and doesn't mention polyglot piranha or the fact that the other versions are considered legacy now.

[conormurray95]

Just to add some thoughts to this one while I remember them as a user with no previous tree-sitter knowledge who just wanted to clean up some flags automatically.

1. I found the rules.toml files really difficult to understand to start with and bounced around the internet for a while wondering how I could actually see the tree my code produced to try and build new rules until I found https://tree-sitter.github.io/tree-sitter/playground in the end. Before that I'd built the tree-sitter-cli and piped it's output into files to review which wasn't ideal. In an ideal world either a blog or specific .md file taking a user through one of the demo examples and explaining how to see the tree the code generates, why the rule does what it does and how to run it would be great for understanding. The demos themselves were really helpful but I didn't have much clue how or why they did what they did for quite a while.
2. I've yet to find a good way to actually debug new rules I'm creating, https://tree-sitter.github.io/tree-sitter/playground seems to have a query tab but it doesn't actually seem to run the queries to find matches, it just tells you if your syntax is wrong or not as far as I can see. In the end I built a webpage locally based on https://github.com/tree-sitter/tree-sitter/blob/master/lib/binding_web/README.md#web-tree-sitter that would console.log out any matches for my queries but currently the queries and code to be queries are baked into my app so it's not ideal either. It feels like something ideal for a ready made online playground. Have you folks got any better method of creating/debugging new rules? My worry with my local webpage debugger thing is it's fine for me but not plug and play for anyone else who wants to add a new rule in our team.
3. As I explained in Fresh CLI build not working with demo examples #358 (comment) getting the tool up and running as someone without the necessary deps already installed took a while and had a few hurdles. That 5 minute first time run experience of having an install mechanism like homebrew or a published up to date binary in the releases folder would be a great help.

From my POV as a new user I think anything that can be done to shorten the time taken to those 2 milestones of:

1. Getting the tool running
2. Getting the tool running with my code

are good things to bear in mind for a Getting Started flow/guide.

[ketkarameya]

Hey! Thanks a lot. I will bear these things in mind when I get to updating the documentation.

1. My current plan is to have a jupyter notebook walking folks through how to write a rule, how to rewrite, how to compose rules with an edge ... I have been adding new features to Piranha to make a simple tutorial that lowers to barrier to entry to this tooling (as u correctly mention) . I cant
2. Actually if you click at the query tab of tree-sitter, based on your query it will syntax highlight your code . The tags and syntax highlighting colors match. This is hard to "get it" for some folks the first time. Try to take a look again with this in mind. Yes, it is our plan to develop a simple playground to develop piranha rules.
   (About debugging rules .... since its so declarative I do not see what is there to debug). But yes, reasoning about rules will get much easier if there a playground to quickly tinker with rules and play with them.
3. Yes, I know what you mean. But this is slightly more complicated. Because this is Rust we will need a pipeline to release a binary for each platform. Yes, hombrew or cargo (rust pkg manager) are good options. But we are unable to release to cargo because of some technical reason (it doesnt accept unverified dependencies).

[ketkarameya]

If at all you wanna play with rust and experiment making a simple play ground i was thinking to use egui . I guess it might be the fastest and easiest way to develop/maintain a playground for piranha ,. Having wasm bindings => maintaing another interface. Which gets very stressful.