Merge pull request #101 from Herb-AI/documentation

.github/workflows/documentation.yml

@@ -0,0 +1,43 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - documentation # update to match your development branch (master, main, dev, trunk, ...)
+    tags: '*'
+  pull_request:
+
+jobs:
+  build:
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install --upgrade jupyterlab nbconvert
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: '1'
+      - name: Install dependencies
+        run: julia --project=docs/ -e '
+          using Pkg;
+          Pkg.develop(PackageSpec(path=pwd()));
+          Pkg.develop("HerbCore");
+          Pkg.develop("HerbData");
+          Pkg.develop("HerbGrammar");
+          Pkg.develop("HerbInterpret");
+          Pkg.develop("HerbConstraints");
+          Pkg.develop("HerbSearch");
+          Pkg.instantiate()'
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # If authenticating with GitHub Actions token
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # If authenticating with SSH deploy key
+        run: julia --project=docs/ docs/make.jl

.gitignore

@@ -16,6 +16,7 @@ deps/src/
 # Build artifacts for creating documentation generated by the Documenter package
 docs/build/
 docs/site/
+docs/Manifest.toml
 
 # File generated by Pkg, the package manager, based on a corresponding Project.toml
 # It records a fixed state of all packages used by the project. As such, it should not be

docs/Project.toml

@@ -0,0 +1,19 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterTools = "35a29f4d-8980-5a13-9543-d66fff28ecb8"
+Herb = "c09c6b7f-4f63-49de-90d9-97a3563c0f4a"
+HerbConstraints = "1fa96474-3206-4513-b4fa-23913f296dfc"
+HerbCore = "2b23ba43-8213-43cb-b5ea-38c12b45bd45"
+HerbData = "495a3ad3-8034-41b3-a087-aacf2fd71098"
+HerbGrammar = "4ef9e186-2fe5-4b24-8de7-9f7291f24af7"
+HerbInterpret = "5bbddadd-02c5-4713-84b8-97364418cca7"
+HerbSearch = "3008d8e8-f9aa-438a-92ed-26e9c7b4829f"
+HerbSpecification = "6d54aada-062f-46d8-85cf-a1ceaf058a06"
+Pluto = "c3e4b0f8-55cb-11ea-2926-15256bba5781"
+PlutoSliderServer = "2fc8631c-6f24-4c5b-bca7-cbb509c42db4"
+PlutoStaticHTML = "359b1769-a58e-495b-9770-312e911026ad"
+PlutoUI = "7f904dfe-b85e-4ff6-b463-dae2292396a8"
+PyCall = "438e738f-606a-5dbb-bf0a-cddfbfd45ab0"
+
+[compat]
+Documenter = "1"

docs/README.md

@@ -0,0 +1,15 @@
+# Documentation of Herb.jl
+
+This documentation was created using [Documenter.jl](https://documenter.juliadocs.org/stable/man/guide/). 
+
+## Writing documentation
+
+The majority of the documentation of automatically generated from the respective docstrings of each sub-package. 
+There are some pages that were added manually and can be edited likewise. New pages can 1. easily be written in markdown and 2. added to the site-tree by editing `docs/make.jl`. 
+
+## Compiling the documentation
+Compiling is automatically triggered whenever pushing to this branch. If you want to run the documentation locally run `julia --project=. make.jl` in this directory.
+
+## Help!
+
+If help is needed reach out to [THinnerichs](https://github.com/thinnerichs).

docs/make.jl

@@ -0,0 +1,78 @@
+using Documenter
+
+using Pluto, PlutoSliderServer
+
+using Herb
+
+using HerbConstraints
+using HerbSearch
+using HerbGrammar
+using HerbInterpret
+using HerbCore
+using HerbSpecification
+
+# Create md file for tutorial that embeds html file
+basedir = joinpath(@__DIR__, "src", "tutorials")
+html_files = filter!(f -> occursin(r"\.html$", f), readdir(basedir)) # assumes all html file in directory are tutorials
+
+for f in html_files
+    html_path = joinpath(basedir, f)
+    filename = replace(f, ".html" => "")
+    md_path = joinpath(basedir, "$filename.md")
+    content = """
+    # Tutorial $filename
+
+    <iframe src="$html_path" width="100%" height="600px"></iframe> 
+    """
+    open(md_path, "w") do file
+        write(
+            file,
+            content
+        )
+    end
+end
+
+
+makedocs(
+    modules=[HerbConstraints, HerbSearch, HerbGrammar, HerbSpecification, HerbInterpret, HerbCore],
+    authors="PONYs",
+    sitename="Herb.jl",
+    pages=[
+        "Basics" => [
+            "index.md",
+            "install.md",
+            "get_started.md",
+            "concepts.md"
+        ],
+        "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",
+        ],
+        "Sub-Modules" => [
+            "HerbCore.jl" => "HerbCore/index.md",
+            "HerbGrammar.jl" => "HerbGrammar/index.md",
+            "HerbSpecification.jl" => "HerbSpecification/index.md",
+            "HerbInterpret.jl" => "HerbInterpret/index.md",
+            "HerbConstraints.jl" => "HerbConstraints/index.md",
+            "HerbSearch.jl" => "HerbSearch/index.md",
+        ],
+    ],
+    format=Documenter.HTML(
+        sidebar_sitename=false,
+        size_threshold=512000,
+    ),
+    warnonly=[:missing_docs, :cross_references, :doctest]
+)
+
+deploydocs(;
+    repo="github.com/Herb-AI/Herb.jl.git",
+    devbranch="documentation",
+    # devurl="dev",
+    push_preview=true
+)
+

docs/src/HerbConstraints/index.md

@@ -0,0 +1,15 @@
+# [HerbConstraints.jl Documentation](@id HerbConstraints_docs)
+
+```@meta
+CurrentModule=HerbConstraints
+```
+
+```@autodocs
+Modules = [HerbConstraints]
+Order   = [:type, :const, :macro, :function]
+```
+
+## Index
+
+```@index
+```

docs/src/HerbCore/index.md

@@ -0,0 +1,15 @@
+# [HerbCore.jl Documentation](@id HerbCore_docs)
+
+```@meta
+CurrentModule=HerbCore
+```
+
+```@autodocs
+Modules = [HerbCore]
+Order   = [:type, :const, :macro, :function]
+```
+
+## Index
+
+```@index
+```

docs/src/HerbGrammar/index.md

@@ -0,0 +1,15 @@
+# [HerbGrammar.jl Documentation](@id HerbGrammar_docs)
+
+```@meta
+CurrentModule=HerbGrammar
+```
+
+```@autodocs
+Modules = [HerbGrammar]
+Order   = [:type, :const, :macro, :function]
+```
+
+## Index
+
+```@index
+```

docs/src/HerbInterpret/index.md

@@ -0,0 +1,15 @@
+# [HerbInterpret.jl Documentation](@id HerbInterpret_docs)
+
+```@meta
+CurrentModule=HerbInterpret
+```
+
+```@autodocs
+Modules = [HerbInterpret]
+Order   = [:type, :const, :macro, :function]
+```
+
+## Index
+
+```@index
+```

docs/src/HerbSearch/index.md

@@ -0,0 +1,27 @@
+# [HerbSearch.jl Documentation](@id HerbSearch_docs)
+
+```@meta
+CurrentModule=HerbSearch
+```
+
+```@autodocs
+Modules = [HerbSearch]
+Order   = [:type, :const, :macro, :function]
+```
+
+The HerbSearch package takes care of all operations related to searching for the desired program. This includes
+- the functionality to sample a certain program given a grammar,
+- the implementation of several heuristic functions,
+- searching for a program that satisfies the specification, and
+- implementations of several search algorithms in terms of how they enumerate the search space
+  - Breadth-First Search 
+  - Depth-First Search 
+  - Metropolis Hastings 
+  - Very Large Scale Neighbourhood Search 
+  - Simulated Annealing
+  - Genetic Search
+
+## Index
+
+```@index
+```

docs/src/HerbSpecification/index.md

@@ -0,0 +1,15 @@
+# [HerbSpecification.jl Documentation](@id HerbSpecification_docs)
+
+```@meta
+CurrentModule=HerbSpecification
+```
+
+```@autodocs
+Modules = [HerbSpecification]
+Order   = [:type, :const, :macro, :function]
+```
+
+## Index
+
+```@index
+```