Add Julia API reference to Quarto. Add doctests. (#470)

Deltares · Aug 2, 2023 · 6d22c1a · 6d22c1a
1 parent d44786a
commit 6d22c1a
Show file tree

Hide file tree

Showing 10 changed files with 70 additions and 4 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -62,6 +62,12 @@ jobs:
           quartodoc build
           rm objects.json
 
+      - name: Generate Julia docs
+        working-directory: docs
+        run: |
+          julia --project -e "using Pkg; Pkg.instantiate()"
+          julia --project make.jl
+
       - name: Render Quarto Project
         run: "quarto render docs --to html --execute"
 

diff --git a/core/Project.toml b/core/Project.toml
@@ -49,6 +49,7 @@ julia = "1.9"
 [extras]
 Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595"
 CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 IOCapture = "b5f81e59-6552-4d32-b1f0-c071b021bf89"
 Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
 SafeTestsets = "1bc83da4-3b8d-516f-aca4-4fe02f6d838f"
@@ -58,4 +59,4 @@ Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 TestReports = "dcd651b4-b50a-5b6b-8f22-87e9f253a252"
 
 [targets]
-test = ["Aqua", "CSV", "IOCapture", "Logging", "SafeTestsets", "TerminalLoggers", "Test", "TestReports", "TOML"]
+test = ["Aqua", "CSV", "Documenter", "IOCapture", "Logging", "SafeTestsets", "TerminalLoggers", "Test", "TestReports", "TOML"]
diff --git a/core/src/utils.jl b/core/src/utils.jl
@@ -140,9 +140,11 @@ For an element `id` and a vector of elements `ids`, get the range of indices of
 consecutive block of `id`.
 Returns the empty range `1:0` if `id` is not in `ids`.
 
-```
-#                  1 2 3 4 5 6 7 8 9
-findlastgroup(2, [5,4,2,2,5,2,2,2,1])  # -> 6:8
+```jldoctest
+#                         1 2 3 4 5 6 7 8 9
+Ribasim.findlastgroup(2, [5,4,2,2,5,2,2,2,1])
+# output
+6:8
 ```
 """
 function findlastgroup(id::Int, ids::AbstractVector{Int})::UnitRange{Int}

diff --git a/core/test/docs.jl b/core/test/docs.jl
@@ -0,0 +1,6 @@
+using Test, Documenter, Ribasim
+DocMeta.setdocmeta!(Ribasim, :DocTestSetup, :(using Ribasim); recursive = true)
+
+@testset "Doctests" begin
+    doctest(Ribasim; manual = false)
+end
diff --git a/core/test/runtests.jl b/core/test/runtests.jl
@@ -14,5 +14,6 @@ using SafeTestsets: @safetestset
     @safetestset "Utility functions" include("utils.jl")
     @safetestset "Control" include("control.jl")
     @safetestset "Time" include("time.jl")
+    @safetestset "Docs" include("docs.jl")
     Aqua.test_all(Ribasim; ambiguities = false)
 end
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -1,4 +1,6 @@
 [deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterMarkdown = "997ab1e6-3595-5248-9280-8efb232c3433"
 InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
 JSON3 = "0f8b85d8-7281-11e9-16c2-39a750bddbf1"
 

diff --git a/docs/_quarto.yml b/docs/_quarto.yml
@@ -30,6 +30,7 @@ website:
         - core/index.qmd
         - core/usage.qmd
         - core/equations.qmd
+        - build/index.md
     - title: "Python tooling"
       contents:
         - python/index.qmd

diff --git a/docs/contribute/core.qmd b/docs/contribute/core.qmd
@@ -109,6 +109,13 @@ quartodoc build
 You typically only have to run this once, or if you want to check out how it looks after
 changing Python docstrings.
 
+The Julia API reference is created using Documenter.jl by running this command from the `docs/` folder:
+
+```bash
+julia --project -e "using Pkg; Pkg.instantiate()"  # needed once
+julia --project make.jl  # after changing the Julia docstrings
+```
+
 In order to preview documentation you can run the following command from the `docs/` folder.
 Afterwards, a browser tab will open with the rendered documentation, updating it as you
 make changes.

diff --git a/docs/make.jl b/docs/make.jl
@@ -0,0 +1,16 @@
+push!(LOAD_PATH, "../core/")
+using Documenter, Ribasim
+using DocumenterMarkdown
+
+DocMeta.setdocmeta!(Ribasim, :DocTestSetup, :(using Ribasim); recursive = true)
+
+makedocs(;
+    modules = [Ribasim],
+    format = Markdown(),
+    repo = "https://github.com/Deltares/Ribasim.jl/blob/{commit}{path}#L{line}",
+    sitename = "Ribasim.jl",
+    authors = "Deltares",
+    doctest = false,  # we doctest as part of normal CI
+)
+
+# TODO Make fully compatible with Quarto, like LaTeX and references
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -0,0 +1,24 @@
+# API Reference
+*This is the private internal documentation of the Ribasim API.*
+
+```@contents
+```
+
+## Functions
+
+```@autodocs
+Modules = [Ribasim, Ribasim.config]
+Order   = [:function]
+```
+
+## Types
+
+```@autodocs
+Modules = [Ribasim, Ribasim.config]
+Order   = [:type]
+```
+
+## Index
+
+```@index
+```