improve local docs workflow (#31)

Author: lucaferranti

.github/workflows/CI.yml

@@ -51,7 +51,7 @@ jobs:
         with:
           version: '1'
       - name: Install dependencies
-        run: julia --project=docs -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate();'
+        run: julia --project=docs docs/setup.jl
       - name: Build and deploy
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

docs/Project.toml

@@ -6,6 +6,7 @@ ImageCore = "a09fc81d-aa75-5fe9-8630-4744c3626534"
 ImageFiltering = "6a3955dd-da59-5b1f-98d4-e7296123deb5"
 ImageShow = "4e3cecfd-b093-5904-9786-8bbb286a6a31"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
+LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 TestImages = "5e47fb64-e119-507b-a336-dd2b206d9990"
 
@@ -14,5 +15,6 @@ DocThemeIndigo = "0.1.3"
 ImageCore = "0.9.4"
 ImageFiltering = "0.7.3"
 Literate = "2.14"
+LiveServer = "1.2.7"
 Plots = "1.38"
 TestImages = "1.7"

docs/liveserver.jl

@@ -0,0 +1,19 @@
+import Pkg
+
+Pkg.activate(@__DIR__)
+
+using LiveServer
+
+servedocs(; literate_dir = joinpath("docs", "src", "literate"),
+          skip_dirs = [
+              joinpath("docs", "src", "notebooks"),
+              joinpath("docs", "src", "tutorials"),
+              joinpath("docs", "src", "applications"),
+          ],
+          skip_files = [
+              joinpath("docs", "src", "api", "logical.md"),
+              joinpath("docs", "src", "api", "memberships.md"),
+              joinpath("docs", "src", "assets", "indigo.css"),
+          ],
+          launch_browser = true,
+          verbose = true)

docs/make.jl

@@ -3,13 +3,7 @@ ENV["GKSwstype"] = "100"
 const IS_CI = get(ENV, "CI", "false") == "true"
 
 import Pkg
-
-if !IS_CI
-    Pkg.activate(@__DIR__)
-    Pkg.instantiate()
-end
-
-Pkg.add(Pkg.PackageSpec(name = "Documenter", rev = "30baed5")) # TODO remove once Documenter 0.28 is released
+Pkg.activate(@__DIR__)
 
 using Documenter
 using DocThemeIndigo
@@ -182,6 +176,4 @@ makedocs(;
 # DEPLOY #
 ##########
 
-if IS_CI
-    deploydocs(; repo = "github.com/lucaferranti/FuzzyLogic.jl", push_preview = true)
-end
+IS_CI && deploydocs(; repo = "github.com/lucaferranti/FuzzyLogic.jl", push_preview = true)

docs/setup.jl

@@ -0,0 +1,9 @@
+import Pkg
+
+Pkg.activate(@__DIR__)
+Pkg.develop(Pkg.PackageSpec(path = joinpath(@__DIR__, "..")))
+Pkg.instantiate()
+
+# TODO remove once Documenter 0.28 is released
+# this is to get both the edit link and a the github link
+Pkg.add(Pkg.PackageSpec(name = "Documenter", rev = "30baed5"))

docs/src/contributing.md

@@ -110,13 +110,25 @@ include("test/runtests.jl")
 
 ## Working on the documentation
 
-* You can build the documentation locally with
+### Local setup
+The first time you start working on the documentation locally, you will need to install all needed dependencies. To do so, run
 
 ```
-julia --project=docs docs/make.jl
+julia docs/setup.jl
 ```
 
-* Tutorials and applications are written using [Literate.jl](https://github.com/fredrikekre/Literate.jl), hence if working on those, you should edit the source file under the `literate` folder and not directly the markdown.
+This needs to be done only the fist time (if you don't have `docs/Manifest.toml`) or any time the Manifest becomes outdated.
+
+Next, you can build the documentation locally by running
+
+```
+julia docs/liveserver.jl
+```
+
+This will open a preview of the documentation in your browser and watch the documentation source files, meaning the preview will automatically update on every documentation change.
+
+### Working with literate.
+* Tutorials and applications are written using [Literate.jl](https://github.com/fredrikekre/Literate.jl). Hence, do not directly edit the markdown files under `docs/src/tutorials` and `docs/src/applications`, edit instead the corresponding julia files under `docs/src/literate`. 
 
 ## Further reading