Improvements to the documentation: feedback from a new user

Hi 😃 I have been building a parser with lark, and got it working by reading docs and examples. However it was not straightforward.

The Github wiki is harder to navigate than readthedocs or other similar alternatives like mkdocs and it’s a painful experience if you don’t know what you are looking for.

The tutorials are really good to get an idea of what lark can do in simple situation, but bridging the gap to real-world usage takes a while because is very hard to find good and descriptive EBNF docs. I worked by googling and glueing pieces together. You should consider on adding links to more EBNF-related material or covering more of the EBNF syntax, for example I did not find anything about <INDENT> and <DEDENT>

The examples are good, but the best ones are in the examples folder linked from the page and nothing else is said about them. The indented tree example is very good, but a distracted reader might easily miss it or assume that the important ones are in the wiki.

The classes reference is missing the Indenter class and details on implementing a custom indenter class are absent from the docs. The Tree class documentation is particularly unhelpful:

• pretty: never mentioned anywhere else, which I found strange given how helpful this function his
• find_pred: Returns all nodes of the tree that evaluate pred(node) as true. It’s never said what a pred is, so the meaning of this remains obscure.
• find_data: Returns all nodes of the tree whose data equals the given data. Does not say what kind of data expects or in which format.
• iter_subtrees: Iterates over all the subtrees, never returning to the same node twice[...] It looks important, since it’s in the docs it might be, but does not explain how to profit from this method

[erezsh]

@brupelo Added a cheatsheet, what do you think? https://github.com/lark-parser/lark/blob/master/docs/lark_cheatsheet.pdf

[brupelo]

I’m thinking of writing a grammar cheatsheet. Would that help?

That’d be helpful indeed, some guys like me are just lazy when it comes to read very meaty doc/specs pages, even more if they’ve been generated automatically out of the source code. I do really love using lightweight docs like cheatsheets or learning by examples… Good about that type of learning is you know what’s possible to achieve with a particular piece of tech and then… if you want to know more, you just dig into the source code, instead reading nonsense docs. Source code should be self-explanatory by itself.

Coming up with good documentation/examples/use-cases is one of the most important things to make a project become more popular… at the end of the day, people is more interested on how to use a piece of tech more than the piece of tech itself.

Examples:

• pandas: example1 or example2
• numpy
• matplotlib
• scikit: example1 or example2

So… yeah, more examples & cheatsheets and less boring docs ;D