Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Part 1: doc restructure, introduce categories #1364

Open
wants to merge 8 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/forest.rst
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
Working with the SPPF
=====================
Shared packed parse forest (SPPF)
=================================

When parsing with Earley, Lark provides the ``ambiguity='forest'`` option
to obtain the shared packed parse forest (SPPF) produced by the parser as
Expand Down
2 changes: 1 addition & 1 deletion docs/how_to_develop.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# How to develop Lark - Guide
# Developing Lark
tomschr marked this conversation as resolved.
Show resolved Hide resolved

There are many ways you can help the project:

Expand Down
2 changes: 1 addition & 1 deletion docs/how_to_use.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# How To Use Lark - Guide
# Using Lark
tomschr marked this conversation as resolved.
Show resolved Hide resolved

## Work process

Expand Down
123 changes: 41 additions & 82 deletions docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -6,40 +6,6 @@
Welcome to Lark's documentation!
================================

.. toctree::
:maxdepth: 2
:caption: Overview
:hidden:

philosophy
features
parsers

.. toctree::
:maxdepth: 2
:caption: Tutorials & Guides
:hidden:

json_tutorial
how_to_use
how_to_develop
recipes
examples/index


.. toctree::
:maxdepth: 2
:caption: Reference
:hidden:

grammar
tree_construction
classes
visitors
forest
tools



Lark is a modern parsing library for Python. Lark can parse any context-free grammar.

Expand All @@ -50,6 +16,8 @@ Lark provides:
- Automatic tree construction, inferred from your grammar
- Fast unicode lexer with regexp support, and automatic line-counting

Refer to the section :doc:`features` for more information.


Install Lark
--------------
Expand All @@ -58,65 +26,56 @@ Install Lark

$ pip install lark

Syntax Highlighting
-------------------

- `Sublime Text & TextMate`_
- `Visual Studio Code`_ (Or install through the vscode plugin system)
- `Intellij & PyCharm`_
- `Vim`_
- `Atom`_
-------

How the documentation is organized
----------------------------------

A high-level overview of how it’s organized will help you know where to look for certain things:

.. _Sublime Text & TextMate: https://github.com/lark-parser/lark_syntax
.. _Visual Studio Code: https://github.com/lark-parser/vscode-lark
.. _Intellij & PyCharm: https://github.com/lark-parser/intellij-syntax-highlighting
.. _Vim: https://github.com/lark-parser/vim-lark-syntax
.. _Atom: https://github.com/Alhadis/language-grammars
* Tutorials take you by the hand through a series of steps how to get familiar with Lark. Start here if you’re new to Lark.
* How-to guides are bite-sized, problem-specific solutions to common tasks.
* Addendums covers background information to Lark.
* References contain syntax and semantics reference material for Lark.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I personally don't really like if documentation feels the need to explain how it works. The naming of sections should be good enough that it's obvious. This is IMO the case for Tutorials, Addendum and References. How-to is a bit less clear, Recipes is a better name there IMO.

Even if we keep this list, the first sentence that explains that this is an explanations of sections is definitely not needed and just represents noise.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's a fair point. Actually, I had stolen this part from the Django documentation. Maybe for the Django docs it's justified as their work is huge.

I have no problem to remove it, but let's give it a bit more time to see what others think about this.


Resources
---------

- :doc:`philosophy`
- :doc:`features`
- `Examples`_
- `Third-party examples`_
- `Online IDE`_
- Tutorials
-------

.. toctree::
:maxdepth: 2
:caption: First steps

- `How to write a DSL`_ - Implements a toy LOGO-like language with
an interpreter
- :doc:`json_tutorial` - Teaches you how to use Lark
- Unofficial
json_tutorial
examples/index
features

- `Program Synthesis is Possible`_ - Creates a DSL for Z3
- `Using Lark to Parse Text - Robin Reynolds-Haertle (PyCascades 2023) <https://www.youtube.com/watch?v=CeOtqlh0UuQ>`_ (video presentation)

- Guides
.. toctree::
:maxdepth: 2
:caption: How-to guides

- :doc:`how_to_use`
- :doc:`how_to_develop`
recipes
how_to_use
how_to_develop

- Reference

- :doc:`grammar`
- :doc:`tree_construction`
- :doc:`visitors`
- :doc:`forest`
- :doc:`classes`
- :doc:`tools`
- `Cheatsheet (PDF)`_
.. toctree::
:maxdepth: 2
:caption: Addendum

- Discussion
philosophy
parsers
resources

- `Gitter`_
- `Forum (Google Groups)`_

.. toctree::
:maxdepth: 2
:caption: Reference

.. _Examples: https://github.com/lark-parser/lark/tree/master/examples
.. _Third-party examples: https://github.com/ligurio/lark-grammars
.. _Online IDE: https://lark-parser.org/ide
.. _How to write a DSL: http://blog.erezsh.com/how-to-write-a-dsl-in-python-with-lark/
.. _Program Synthesis is Possible: https://www.cs.cornell.edu/~asampson/blog/minisynth.html
.. _Cheatsheet (PDF): _static/lark_cheatsheet.pdf
.. _Gitter: https://gitter.im/lark-parser/Lobby
.. _Forum (Google Groups): https://groups.google.com/forum/#!forum/lark-parser
grammar
tree_construction
classes
visitors
forest
tools
41 changes: 41 additions & 0 deletions docs/resources.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# Resources

- [philosophy](philosophy.md)
- [features](features.md)
- [Examples](https://github.com/lark-parser/lark/tree/master/examples)
- [Third-party examples](https://github.com/ligurio/lark-grammars)
- [Online IDE](https://lark-parser.org/ide)
- Tutorials

- [How to write a DSL](http://blog.erezsh.com/how-to-write-a-dsl-in-python-with-lark/) - Implements a toy LOGO-like language with
an interpreter
- :doc:`json_tutorial` - Teaches you how to use Lark
- Unofficial

- [Program Synthesis is Possible](https://www.cs.cornell.edu/~asampson/blog/minisynth.html) - Creates a DSL for Z3
- [Using Lark to Parse Text - Robin Reynolds-Haertle (PyCascades 2023)](https://www.youtube.com/watch?v=CeOtqlh0UuQ) (video presentation)

- Syntax Highlighting

- [Sublime Text & TextMate](https://github.com/lark-parser/lark_syntax)
- [Visual Studio Code](https://github.com/lark-parser/vscode-lark) (Or install through the vscode plugin system)
- [Intellij & PyCharm](https://github.com/lark-parser/intellij-syntax-highlighting)
- [Vim](https://github.com/lark-parser/vim-lark-syntax)
- [Atom](https://github.com/Alhadis/language-grammars)

- Reference

- [Cheatsheet (PDF)](_static/lark_cheatsheet.pdf)
<!--
- [grammar](grammar.md)
- [tree_construction](tree_construction.md)
- :doc:`visitors.rst`
- :doc:`forest.rst`
- :doc:`classes.rst`
- [tools](tools.md) -->


- Discussion

- [Gitter](https://gitter.im/lark-parser/Lobby)
- [Forum (Google Groups)](https://groups.google.com/forum/#!forum/lark-parser)