Merge pull request #118 from Herb-AI/documentation

Documentation - tutorial updates

docs/Project.toml

@@ -9,11 +9,14 @@ HerbGrammar = "4ef9e186-2fe5-4b24-8de7-9f7291f24af7"
 HerbInterpret = "5bbddadd-02c5-4713-84b8-97364418cca7"
 HerbSearch = "3008d8e8-f9aa-438a-92ed-26e9c7b4829f"
 HerbSpecification = "6d54aada-062f-46d8-85cf-a1ceaf058a06"
+Kroki = "b3565e16-c1f2-4fe9-b4ab-221c88942068"
 Pluto = "c3e4b0f8-55cb-11ea-2926-15256bba5781"
 PlutoSliderServer = "2fc8631c-6f24-4c5b-bca7-cbb509c42db4"
 PlutoStaticHTML = "359b1769-a58e-495b-9770-312e911026ad"
 PlutoUI = "7f904dfe-b85e-4ff6-b463-dae2292396a8"
+PrettyTables = "08abe8d2-0d0c-5749-adfa-8a2ac140af0d"
 PyCall = "438e738f-606a-5dbb-bf0a-cddfbfd45ab0"
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [compat]
 Documenter = "1"

docs/make.jl

@@ -15,6 +15,7 @@ tutorials_dir = joinpath(dirname(@__DIR__), "docs", "src", "tutorials")
 Pkg.activate(@__DIR__)
 build(tutorials_dir)
 
+# NOTE: tutorials should be added manually on the homepage (src/index.md)
 makedocs(
     modules=[HerbConstraints, HerbSearch, HerbGrammar, HerbSpecification, HerbInterpret, HerbCore],
     authors="PONYs",

docs/src/get_started.md

@@ -1,6 +1,6 @@
 # Getting Started
 
-You can either paste this code into the Julia REPL or into a seperate file, e.g. `get_started.jl`. If using a separate file you can execute using `julia get_started.jl` or `julia --project=. get_started.jl` depending on whether you installed Herb.jl globally or in a project.
+You can either paste this code into the Julia REPL or into a separate file, e.g. `get_started.jl`. If using a separate file you can execute using `julia get_started.jl` or `julia --project=. get_started.jl` depending on whether you installed Herb.jl globally or in a project.
 
 To begin, we need to import all needed packages using
 
@@ -30,7 +30,7 @@ Second, the problem specification can be provided using e.g. input/output exampl
 problem = Problem([IOExample(Dict(:x => x), 2x+1) for x ∈ 1:5])
 ```
 
-The problem is given now, let us search for a solution with `HerbSearch`. For now we will just use the default parameters searching for a satisfying program over the grammar, given the problem and a starting symbol using
+The problem is given now, let us search for a solution with `HerbSearch`. For now, we will just use the default parameters searching for a satisfying program over the grammar, given the problem and a starting symbol using
 
 ```julia
 iterator = BFSIterator(g, :Number, max_depth=5)

docs/src/index.md

@@ -7,9 +7,9 @@ CurrentModule=Herb
 
 ## Why Herb.jl?
 
-When writing research software we almost always investigate highly specific properties or algorithms of our domain, leading to us building the tools from scratch over and over again. The very same holds for the field of program synthesis: Tools are hard to run, benchmarks are hard to get and prepare, and its hard to adapt our existing code to a novel idea.
+When writing research software we almost always investigate highly specific properties or algorithms of our domain, leading to us building the tools from scratch over and over again. The very same holds for the field of program synthesis: Tools are hard to run, benchmarks are hard to get and prepare, and it is hard to adapt our existing code to a novel idea.
 
-Herb.jl will take care of this for you and helps you defining, solving and extending your program synthesis problems.
+Herb.jl will take care of this for you and helps you in defining, solving and extending your program synthesis problems.
 
 Herb.jl provides...
 - a unified and universal framework for program synthesis
@@ -46,6 +46,17 @@ Pages = ["install.md", "get_started.md", "concepts.md"]
 ```
 
 ## Advanced content
-
 ```@contents
+Pages = [p * "/index.md" for p in readdir(joinpath(dirname(@__FILE__), "..", "src")) if occursin("Herb", p)]
+Depth = 1
 ```
+
+## Tutorials
+To familiarize yourself with Herb, we have created several tutorials:
+- [A more verbose getting started with Herb.jl](tutorials/getting_started_with_herb.md)
+- [Defining Grammars in Herb.jl](tutorials/defining_grammars.md)
+- [Advanced Search Procedures](tutorials/advanced_search.md)
+- [Top Down Iterator](tutorials/TopDown.md)
+- [Getting started with Constraints](tutorials/getting_started_with_constraints.md)
+- [Working with custom interpreters](tutorials/working_with_interpreters.md)
+- [Abstract Syntax Trees](tutorials/abstract_syntax_trees.md)

docs/src/install.md

@@ -2,7 +2,7 @@
 
 Before installing Herb.jl, ensure that you have a running Julia distribution installed (Julia version 1.7 and above were tested). 
 
-Thanks to Julia's package management, installing Herb.jl is very straighforward. 
+Thanks to Julia's package management, installing Herb.jl is very straightforward. 
 Activate the default Julia REPL using
 
 ```shell

docs/src/tutorials/TopDown.md

@@ -2,8 +2,18 @@
 
 The core building block in Herb is a program iterator.
 A program iterator represents a walk through the program space; different iterators provide different ways of iterating through program space. 
-From the program synthesis point of view, program iterators actaully represent program spaces.
-
+From the program synthesis point of view, program iterators actually represent program spaces.
+
+```mermaid
+    flowchart TD
+    id1((13)) ---
+    id2((6))
+    id1 --- id3((12))
+    id4((11))
+    id5((4))
+    id3 --- id4
+    id3 --- id5
+```
 
 ### Iterator hierarchy
 
@@ -20,15 +30,15 @@ Stochastic search further provides specific iterators:
  - `VLNSearchIterator` for traversals with Very Large Neighbourhood Search
  - `SASearchIterator` for Simulated Annealing
 
- We provide generic and customiseable implementations of each of these iterators, so that users can easily tweak them by through multiple dispatch. Keep reading!
+ We provide generic and customisable implementations of each of these iterators, so that users can easily tweak them by through multiple dispatch. Keep reading!
 
 
 ### Iterator design
 
 Program iterators follow the standard Julia `Iterator` interface.
 That is, every iterator should implement two functions:
  - `iterate(<:ProgramIterator)::(RuleNode,Any)` to get the first program. The function takes a program iterator as an input, returning the first program and a state (which can be anything)
- - `iterate(<:ProgramIterator,Any)::(RuleNode,Any)` to get the consequtive programs. The function takes the progrma iterator and the state from the previous iteration, and return the next program and the next state.
+ - `iterate(<:ProgramIterator,Any)::(RuleNode,Any)` to get the consecutive programs. The function takes the program iterator and the state from the previous iteration, and return the next program and the next state.
 
 
 
@@ -38,9 +48,9 @@ That is, every iterator should implement two functions:
 
 ## Top Down iterator
 
-We illustarate how to build iterators with a Top Down iterator.
+We illustrate how to build iterators with a Top Down iterator.
 The top Down iterator is build as a best-first iterator: it maintains a priority queue of programs and always pops the first element of the queue. 
-The iterator is customiseable through the following functions:
+The iterator is customisable through the following functions:
 - priority_function: dictating the order of programs in the priority queue
 - derivation_heuristic: dictating in which order to explore the derivations rules within a single hole
 - hole_heuristic: dictating which hole to expand next
@@ -110,7 +120,7 @@ The `SolverState` and `UniformIterator` are specialised data structure to improv
 
 Herb uses a data structure of `UniformTrees` to represent all programs with an AST of the same shape, where each node has the same type. the `UniformIterator` is an iterator efficiently iterating over that structure.
 
-The `SolverState` represents non-uniform trees -- ASTs whose shape we haven't compeltely determined yet. `SolverState` is used as an intermediate representation betfore we reach `UniformTree`s on which partial constraint propagation is done.
+The `SolverState` represents non-uniform trees -- ASTs whose shape we haven't completely determined yet. `SolverState` is used as an intermediate representation before we reach `UniformTree`s on which partial constraint propagation is done.
 
 In principle, you should never construct ASTs yourself directly; you should leave that to the constraint solver.
 
@@ -131,7 +141,7 @@ function _find_next_complete_tree(
 
 ```
 
-If it is a Uniform Iterator, that is an interator where all the holes have the same shape, then it iterates over the solutions.
+If it is a Uniform Iterator, that is an iterator where all the holes have the same shape, then it iterates over the solutions.
 
 ``` julia