diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 7dd281c38..0e34989d0 100644 --- 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 index 983f2f2d6..a4d7db22e 100644 --- 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 index cc209ff67..11219d7c0 100644 --- 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 new file mode 100644 index 000000000..8742cdb04 --- /dev/null +++ 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 index 3af4b7a97..e03cbdfbe 100644 --- 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 index 9726df2c8..2a7cc1458 100644 --- 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 index 4b576fe11..61d0081d8 100644 --- 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 index 772b0edff..00f30fb63 100644 --- 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 new file mode 100644 index 000000000..9c0657009 --- /dev/null +++ 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 new file mode 100644 index 000000000..2c05208d6 --- /dev/null +++ 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 +```