Merge pull request #151 from Herb-AI/refactor/documentation-ci

Refactor documentation workflow

Author: pwochner

.github/workflows/documentation.yml

@@ -3,7 +3,7 @@ name: Documentation
 on:
   push:
     branches:
-      - documentation # update to match your development branch (master, main, dev, trunk, ...)
+      - master # update to match your development branch (master, main, dev, trunk, ...)
     tags: '*'
   pull_request:
 
@@ -14,14 +14,6 @@ jobs:
     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'

Project.toml

@@ -1,7 +1,7 @@
 name = "Herb"
 uuid = "c09c6b7f-4f63-49de-90d9-97a3563c0f4a"
 authors = ["Jaap de Jong <jaapdejong15@gmail.com>", "Tilman Hinnerichs <t.r.hinnerichs@tudelft.nl>", "Sebastijan Dumancic <s.dumancic@tudelft.nl>"]
-version = "0.6.0"
+version = "0.6.1"
 
 [deps]
 HerbConstraints = "1fa96474-3206-4513-b4fa-23913f296dfc"

docs/Project.toml

@@ -1,5 +1,6 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterMermaid = "a078cd44-4d9c-4618-b545-3ab9d77f9177"
 DocumenterTools = "35a29f4d-8980-5a13-9543-d66fff28ecb8"
 Herb = "c09c6b7f-4f63-49de-90d9-97a3563c0f4a"
 HerbConstraints = "1fa96474-3206-4513-b4fa-23913f296dfc"
@@ -11,9 +12,7 @@ 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"

docs/README.md

@@ -7,9 +7,33 @@ This documentation was created using [Documenter.jl](https://documenter.juliadoc
 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`. 
 
+## Tutorial notebooks
+The tutorials are written as Pluto notebooks and can be found in `docs/src/tutorials/`. To ensure that both CI builds and manual execution use the same dependencies as defined in `docs/Project.toml`, each tutorial notebook should include the following cell at the top:
+```julia
+begin
+    import Pkg
+    Pkg.activate(Base.current_project())
+    Pkg.instantiate()
+    
+    # Your package imports ...
+end
+```
+Note that this disables Pluto's built-in package manager.
+
 ## 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.
+Compiling is automatically triggered whenever pushing to this branch. 
+
+If you want to run the documentation locally run `julia --project=. make.jl` from this directory.
+Once built successfully, the documentation is generated in the directory `docs/build`. You can preview it by either opening `docs/build/index.html` in a browser,
+or by using `LiveServer`:
+```
+julia --project=. -e 'using Pkg; Pkg.add("LiveServer"); using LiveServer; serve(dir="build")'  
+```
+The documentation will be available at http://localhost:8000.
 
 ## Help!
 
 If help is needed reach out to [THinnerichs](https://github.com/thinnerichs).
+
+#### Note
+The `other` folder contains some old material that is not hosted on our website. 

docs/build_notebooks.jl

@@ -1,9 +1,14 @@
 using PlutoStaticHTML
 
+"""
+Builds the Pluto notebooks in the specified directory. 
+As part of the build, all notebooks are executed to make sure there is no 
+deprecated code. 
+"""
 function build(tutorials_dir)
     @info "Building notebooks in $tutorials_dir"
     use_distributed = false
     output_format = documenter_output
     bopts = BuildOptions(tutorials_dir; use_distributed, output_format)
     build_notebooks(bopts)
-end
+end

docs/make.jl

@@ -1,4 +1,5 @@
 using Documenter: HTML, deploydocs, makedocs
+using DocumenterMermaid
 using Herb
 using Pkg
 using PlutoStaticHTML
@@ -11,15 +12,22 @@ build(tutorials_dir)
 
 # NOTE: tutorials should be added manually on the homepage (src/index.md)
 makedocs(
-    modules=[HerbConstraints, HerbSearch, HerbGrammar, HerbSpecification, HerbInterpret, HerbCore],
+    modules=[
+        HerbConstraints,
+        HerbSearch,
+        HerbGrammar,
+        HerbSpecification,
+        HerbInterpret,
+        HerbCore,
+    ],
     authors="PONYs",
     sitename="Herb.jl",
     pages=[
         "Basics" => [
             "index.md",
             "install.md",
-            "get_started.md",
-            "concepts.md"
+            "Getting Started" => "tutorials/basic_getting_started.md",
+            "concepts.md",
         ],
         "Tutorials" => [
             "A more verbose getting started with Herb.jl" => "tutorials/getting_started_with_herb.md",
@@ -43,13 +51,13 @@ makedocs(
         sidebar_sitename=false,
         size_threshold=2^20,
     ),
-    warnonly=[:missing_docs, :cross_references, :doctest]
+    warnonly=[:missing_docs, :cross_references, :doctest],
 )
 
 deploydocs(;
     repo="github.com/Herb-AI/Herb.jl.git",
-    devbranch="documentation",
+    devbranch="master",
     # devurl="dev",
-    push_preview=true
+    push_preview=true,
 )