Part 1: doc restructure, introduce categories

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,

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

docs/how_to_develop.md

@@ -1,4 +1,4 @@
-# How to develop Lark - Guide
+# Contributing to Lark
 
 There are many ways you can help the project:
 

docs/how_to_use.md

@@ -1,4 +1,4 @@
-# How To Use Lark - Guide
+# Working with Lark
 
 ## Work process
 

docs/index.rst

@@ -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.
 
@@ -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
 --------------
@@ -58,65 +26,52 @@ Install Lark
 
  $ 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
+How the documentation is organized
+----------------------------------
 
-Resources
----------
+A high-level overview of how it’s organized will help you know where to look for certain things:
 
-- :doc:`philosophy`
-- :doc:`features`
-- `Examples`_
-- `Third-party examples`_
-- `Online IDE`_
-- Tutorials
+* 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.
 
- - `How to write a DSL`_ - Implements a toy LOGO-like language with
- an interpreter
- - :doc:`json_tutorial` - Teaches you how to use Lark
- - Unofficial
+.. toctree::
+ :maxdepth: 2
+ :caption: First steps
 
- - `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)
+ json_tutorial
 
-- Guides
 
- - :doc:`how_to_use`
- - :doc:`how_to_develop`
+.. toctree::
+ :maxdepth: 2
+ :caption: How-to guides
 
-- Reference
+ recipes
+ examples/index
+ how_to_use
+ how_to_develop
 
- - :doc:`grammar`
- - :doc:`tree_construction`
- - :doc:`visitors`
- - :doc:`forest`
- - :doc:`classes`
- - :doc:`tools`
- - `Cheatsheet (PDF)`_
 
-- Discussion
+.. toctree::
+ :maxdepth: 2
+ :caption: Addendum
 
- - `Gitter`_
- - `Forum (Google Groups)`_
+ philosophy
+ resources
 
+.. 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
+ features
+ parsers
+ grammar
+ tree_construction
+ classes
+ visitors
+ forest
+ tools

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)
+<!--
+ - [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)