From 843d71d22a0b9684c6f6392be0af6216e3d01462 Mon Sep 17 00:00:00 2001 From: Tom Schraitle Date: Sun, 12 Nov 2023 15:36:19 +0100 Subject: [PATCH 1/8] Doc part 1: Move topics into the right category MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Based in the Diátaxis doc framework, we identified tutorials, how-to guides/recipes, addednum, and references. This commit deals with moving the topics into the "right" category. Related to issue #1360 --- docs/index.rst | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index e69e2b9d0..0e940ea1f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,23 +8,28 @@ Welcome to Lark's documentation! .. toctree:: :maxdepth: 2 - :caption: Overview - :hidden: + :caption: Tutorial - philosophy + json_tutorial + examples/index features - parsers + .. toctree:: :maxdepth: 2 - :caption: Tutorials & Guides - :hidden: + :caption: How-to guides - json_tutorial + recipes how_to_use how_to_develop - recipes - examples/index + + +.. toctree:: + :maxdepth: 2 + :caption: Addendum + + philosophy + parsers .. toctree:: @@ -41,6 +46,7 @@ Welcome to Lark's documentation! + Lark is a modern parsing library for Python. Lark can parse any context-free grammar. Lark provides: From 11c1068c03508566b0260195ca23aa071a96d480 Mon Sep 17 00:00:00 2001 From: Tom Schraitle Date: Sun, 12 Nov 2023 16:21:27 +0100 Subject: [PATCH 2/8] Move additional info into resources The first page should be clean and simple. It acts as a "hub" to let readers select what they need. Move all links into an additional resources.md file and add it to addendum. --- docs/index.rst | 110 +++++++++++----------------------------------- docs/resources.md | 41 +++++++++++++++++ 2 files changed, 66 insertions(+), 85 deletions(-) create mode 100644 docs/resources.md diff --git a/docs/index.rst b/docs/index.rst index 0e940ea1f..bc58dc896 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,9 +6,32 @@ Welcome to Lark's documentation! ================================ + +Lark is a modern parsing library for Python. Lark can parse any context-free grammar. + +Lark provides: + +- Advanced grammar language, based on EBNF +- Three parsing algorithms to choose from: Earley, LALR(1) and CYK +- 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 +-------------- + +.. code:: bash + + $ pip install lark + + +------- + .. toctree:: :maxdepth: 2 - :caption: Tutorial + :caption: First steps json_tutorial examples/index @@ -30,12 +53,12 @@ Welcome to Lark's documentation! philosophy parsers + resources .. toctree:: :maxdepth: 2 :caption: Reference - :hidden: grammar tree_construction @@ -43,86 +66,3 @@ Welcome to Lark's documentation! visitors forest tools - - - - -Lark is a modern parsing library for Python. Lark can parse any context-free grammar. - -Lark provides: - -- Advanced grammar language, based on EBNF -- Three parsing algorithms to choose from: Earley, LALR(1) and CYK -- Automatic tree construction, inferred from your grammar -- Fast unicode lexer with regexp support, and automatic line-counting - - -Install Lark --------------- - -.. code:: bash - - $ pip install lark - -Syntax Highlighting -------------------- - -- `Sublime Text & TextMate`_ -- `Visual Studio Code`_ (Or install through the vscode plugin system) -- `Intellij & PyCharm`_ -- `Vim`_ -- `Atom`_ - -.. _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 - -Resources ---------- - -- :doc:`philosophy` -- :doc:`features` -- `Examples`_ -- `Third-party examples`_ -- `Online IDE`_ -- Tutorials - - - `How to write a DSL`_ - Implements a toy LOGO-like language with - an interpreter - - :doc:`json_tutorial` - Teaches you how to use Lark - - Unofficial - - - `Program Synthesis is Possible`_ - Creates a DSL for Z3 - - `Using Lark to Parse Text - Robin Reynolds-Haertle (PyCascades 2023) `_ (video presentation) - -- Guides - - - :doc:`how_to_use` - - :doc:`how_to_develop` - -- Reference - - - :doc:`grammar` - - :doc:`tree_construction` - - :doc:`visitors` - - :doc:`forest` - - :doc:`classes` - - :doc:`tools` - - `Cheatsheet (PDF)`_ - -- Discussion - - - `Gitter`_ - - `Forum (Google Groups)`_ - - -.. _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 diff --git a/docs/resources.md b/docs/resources.md new file mode 100644 index 000000000..bb03232d8 --- /dev/null +++ b/docs/resources.md @@ -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) + + + +- Discussion + + - [Gitter](https://gitter.im/lark-parser/Lobby) + - [Forum (Google Groups)](https://groups.google.com/forum/#!forum/lark-parser) From 7bf9f9a8c9468dd0922ccc32319bb91505c20a6a Mon Sep 17 00:00:00 2001 From: Tom Schraitle Date: Sun, 12 Nov 2023 17:14:04 +0100 Subject: [PATCH 3/8] Using gerund form in title, omit "how to..." --- docs/forest.rst | 4 ++-- docs/how_to_develop.md | 2 +- docs/how_to_use.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/forest.rst b/docs/forest.rst index 0d843355c..7f5bc5fa1 100644 --- a/docs/forest.rst +++ b/docs/forest.rst @@ -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 diff --git a/docs/how_to_develop.md b/docs/how_to_develop.md index cf95fed06..c2c10716d 100644 --- a/docs/how_to_develop.md +++ b/docs/how_to_develop.md @@ -1,4 +1,4 @@ -# How to develop Lark - Guide +# Developing Lark There are many ways you can help the project: diff --git a/docs/how_to_use.md b/docs/how_to_use.md index 7ba5acf8e..0fae53657 100644 --- a/docs/how_to_use.md +++ b/docs/how_to_use.md @@ -1,4 +1,4 @@ -# How To Use Lark - Guide +# Using Lark ## Work process From eb278fb9848335438c32d4cdd084f0c730006309 Mon Sep 17 00:00:00 2001 From: Tom Schraitle Date: Mon, 13 Nov 2023 08:56:35 +0100 Subject: [PATCH 4/8] Add an high level overview Tell the reader how the Lark documentation is organized. This makes it easier for the reader to choose the necessary topics. --- docs/index.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/index.rst b/docs/index.rst index bc58dc896..f89b9d3f3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -27,6 +27,19 @@ Install Lark $ pip install lark +------- + +How the documentation is organized +---------------------------------- + +A high-level overview of how it’s organized will help you know where to look for certain things: + +* 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. + + ------- .. toctree:: From e7cc4c13029b9a32f07a06bec85b61b8a03fe266 Mon Sep 17 00:00:00 2001 From: Tom Schraitle Date: Thu, 16 Nov 2023 06:47:42 +0100 Subject: [PATCH 5/8] Add review from MegaIng --- docs/how_to_develop.md | 2 +- docs/how_to_use.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/how_to_develop.md b/docs/how_to_develop.md index c2c10716d..59f249663 100644 --- a/docs/how_to_develop.md +++ b/docs/how_to_develop.md @@ -1,4 +1,4 @@ -# Developing Lark +# Contributing to Lark There are many ways you can help the project: diff --git a/docs/how_to_use.md b/docs/how_to_use.md index 0fae53657..2b2a35557 100644 --- a/docs/how_to_use.md +++ b/docs/how_to_use.md @@ -1,4 +1,4 @@ -# Using Lark +# Working with Lark ## Work process From 1014ada35222e716abfdbca79e4a3fc9be40a417 Mon Sep 17 00:00:00 2001 From: Tom Schraitle Date: Thu, 16 Nov 2023 10:32:54 +0100 Subject: [PATCH 6/8] Improve navigation on left TOC sidebar Remove TOC in content as the left TOC sidebar contains [+] markers to unfold/fold the deeper structure. --- docs/conf.py | 3 ++- docs/index.rst | 40 ---------------------------------------- 2 files changed, 2 insertions(+), 41 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index aacf8bba1..405af4df0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -102,7 +102,8 @@ # documentation. # html_theme_options = { - 'prev_next_buttons_location': 'both' + 'prev_next_buttons_location': 'both', + 'collapse_navigation': False, } # Add any paths that contain custom static files (such as style sheets) here, diff --git a/docs/index.rst b/docs/index.rst index f89b9d3f3..925e25f91 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -39,43 +39,3 @@ A high-level overview of how it’s organized will help you know where to look f * Addendums covers background information to Lark. * References contain syntax and semantics reference material for Lark. - -------- - -.. toctree:: - :maxdepth: 2 - :caption: First steps - - json_tutorial - examples/index - features - - -.. toctree:: - :maxdepth: 2 - :caption: How-to guides - - recipes - how_to_use - how_to_develop - - -.. toctree:: - :maxdepth: 2 - :caption: Addendum - - philosophy - parsers - resources - - -.. toctree:: - :maxdepth: 2 - :caption: Reference - - grammar - tree_construction - classes - visitors - forest - tools From 1626dc28c3536a9fbd1db18eef0cd44d15ca70db Mon Sep 17 00:00:00 2001 From: Tom Schraitle Date: Sat, 23 Dec 2023 11:40:29 +0100 Subject: [PATCH 7/8] Accidently remove TOC structure, restored --- docs/index.rst | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/docs/index.rst b/docs/index.rst index 925e25f91..2b6e339bc 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -39,3 +39,39 @@ A high-level overview of how it’s organized will help you know where to look f * Addendums covers background information to Lark. * References contain syntax and semantics reference material for Lark. +.. toctree:: + :maxdepth: 2 + :caption: First steps + + json_tutorial + examples/index + features + + +.. toctree:: + :maxdepth: 2 + :caption: How-to guides + + recipes + how_to_use + how_to_develop + + +.. toctree:: + :maxdepth: 2 + :caption: Addendum + + philosophy + parsers + resources + +.. toctree:: + :maxdepth: 2 + :caption: Reference + + grammar + tree_construction + classes + visitors + forest + tools \ No newline at end of file From c3470e1cdac55cca2431777a06b2ced188dc6336 Mon Sep 17 00:00:00 2001 From: Tom Schraitle Date: Tue, 20 Feb 2024 08:11:23 +0100 Subject: [PATCH 8/8] Move some sections according to @erezsh * Move some sections - parsers -> Reference - features -> Reference - examples/index -> How to guides --- docs/index.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 2b6e339bc..de0c755ae 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -44,8 +44,6 @@ A high-level overview of how it’s organized will help you know where to look f :caption: First steps json_tutorial - examples/index - features .. toctree:: @@ -53,6 +51,7 @@ A high-level overview of how it’s organized will help you know where to look f :caption: How-to guides recipes + examples/index how_to_use how_to_develop @@ -62,13 +61,14 @@ A high-level overview of how it’s organized will help you know where to look f :caption: Addendum philosophy - parsers resources .. toctree:: :maxdepth: 2 :caption: Reference + features + parsers grammar tree_construction classes