Add basic Documenter workflow

.github/workflows/Documenter.yml

@@ -0,0 +1,46 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - 'main'
+    tags: '*'
+    paths-ignore:
+      - '.github/workflows/ci.yml'
+      - '.github/workflows/CompatHelper.yml'
+      - '.github/workflows/TagBot.yml'
+  pull_request:
+    paths-ignore:
+      - '.github/workflows/ci.yml'
+      - '.github/workflows/CompatHelper.yml'
+      - '.github/workflows/TagBot.yml'
+  workflow_dispatch:
+
+concurrency:
+  # Skip intermediate builds: always.
+  # Cancel intermediate builds: only if it is a pull request build.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
+
+jobs:
+  build-docs:
+    permissions:
+      actions: write
+      contents: write
+      pull-requests: read
+      statuses: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: '1'
+          show-versioninfo: true
+      - uses: julia-actions/cache@v2
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
+        run: julia --project=docs --color=yes docs/make.jl

README.md

@@ -1,7 +1,18 @@
 # ParaViewCatalyst.jl
-ParaViewCatalyst.jl provides a Julia interface to Catalyst, used for in-situ
-visualization of simulation data.  
-The Catalyst library for Julia is provided by Catalyst_jll.jl at
+
+<!-- [![Docs-stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://trixi-framework.github.io/ParaViewCatalyst.jl/stable) -->
+[![Docs-dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://trixi-framework.github.io/ParaViewCatalyst.jl/dev)
+[![Slack](https://img.shields.io/badge/chat-slack-e01e5a)](https://join.slack.com/t/trixi-framework/shared_invite/zt-sgkc6ppw-6OXJqZAD5SPjBYqLd8MU~g)
+<!-- [![Build Status](https://github.com/trixi-framework/ParaViewCatalyst.jl/actions/workflows/ci.yml/badge.svg)](https://github.com/trixi-framework/ParaViewCatalyst.jl/actions?query=workflow%3ACI) -->
+<!-- [![Codecov](https://codecov.io/gh/trixi-framework/ParaViewCatalyst.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/trixi-framework/ParaViewCatalyst.jl) -->
+<!-- [![Coveralls](https://coveralls.io/repos/github/trixi-framework/ParaViewCatalyst.jl/badge.svg?branch=main)](https://coveralls.io/github/trixi-framework/ParaViewCatalyst.jl?branch=main) -->
+[![License: MIT](https://img.shields.io/badge/License-MIT-success.svg)](https://opensource.org/licenses/MIT)
+
+**ParaViewCatalyst.jl** provides a Julia interface to
+[Catalyst](https://docs.paraview.org/en/latest/Catalyst/index.html),
+used for in-situ visualization of simulation data.  
+The Catalyst library for Julia is provided automatically as a precompiled binary by Catalyst\_jll.jl
+at
 [JuliaBinaryWrappers](https://github.com/JuliaBinaryWrappers/Catalyst_jll.jl/blob/main/src/Catalyst_jll.jl)
 and [Yggdrasil](https://github.com/JuliaPackaging/Yggdrasil/tree/master/C/Catalyst).
 
@@ -14,7 +25,7 @@ ParaView, this package is geared towards the
 [ParaView implementation](https://docs.paraview.org/en/latest/Catalyst) of the Catalyst API.
 As such ParaView needs to be present on the machine you run your simulation on. In
 particular, a version is required that ships the Catalyst implementation as a library. On
-Linux you should look for `libcatalyst-paraview.so`.  
+Linux you should look for `libcatalyst-paraview.so`.
 Its path has to be set as an environment variable, e.g. by
 ```bash
 export CATALYST_IMPLEMENTATION_PATHS=<path_to_libcatalyst-paraview.so>
@@ -61,20 +72,30 @@ through Conduit nodes, which are required to adhere to the
 [Blueprint](https://docs.paraview.org/en/latest/Catalyst/blueprints.html).
 
 A user-defined ParaView pipeline script can be passed to `catalyst_initialize` using the
-keyword argument `catalyst_pipeline`. By default src/catalyst_pipeline.py is used. This
-script activates live visualization. The data can also be viewed on a remote machine. In
-this case `options.CatalystLiveURL` has to be adjusted to point to the remote machine.
+keyword argument `catalyst_pipeline`. By default src/catalyst_pipeline.py is used, which
+activates live visualization. The data can also be viewed on a remote machine. In this case
+`options.CatalystLiveURL` has to be adjusted to point to the remote machine.
 Once a pipeline in ParaView has been set up, it can be exported as a script by selecting
-"File" from the main menu and then "Save Catalyst State".
+"File" from the main menu and then "Save Catalyst State". It might be required to modify
+this file afterwards.
 
 
 ## Examples
 ParaViewCatalyst.jl is used by [Trixi.jl](https://github.com/trixi-framework/Trixi.jl).
 
+
 ## Authors
-ParaViewCatalyst.jl was initiated by Jake Bolewski (@jakebolewski) at https://github.com/CliMA/
-and is now maintained at https://github.com/trixi-framework.
+ParaViewCatalyst.jl was initiated by Jake Bolewski ([@jakebolewski](https://github.com/jakebolewski))
+at https://github.com/CliMA and is now maintained by
+[Benedict Geihe](https://www.mi.uni-koeln.de/NumSim/dr-benedict-geihe/) (University of Cologne,
+Germany).
 
 
-## License
-ParaViewCatalyst.jl is licensed under the MIT license (see [LICENSE.md](LICENSE.md)).
+## License and contributing
+ParaViewCatalyst.jl is licensed under the MIT license (see [LICENSE.md](LICENSE.md)).  Since
+ParaViewCatalyst.jl is an open-source project, we are very happy to accept contributions from the
+community. Note that we strive to be a friendly, inclusive open-source community and ask all members
+of our community to treat each other decently. To get in touch with the developers,
+[join us on Slack](https://join.slack.com/t/trixi-framework/shared_invite/zt-sgkc6ppw-6OXJqZAD5SPjBYqLd8MU~g)
+or
+[create an issue](https://github.com/trixi-framework/ParaViewCatalyst.jl/issues/new).

docs/.gitignore

@@ -0,0 +1 @@
+build/

docs/Project.toml

@@ -0,0 +1,5 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+
+[compat]
+Documenter = "1"

docs/make.jl

@@ -0,0 +1,73 @@
+using Documenter
+
+# Get ParaViewCatalyst.jl root directory
+paraviewcatalyst_root_dir = dirname(@__DIR__)
+
+# Fix for https://github.com/trixi-framework/Trixi.jl/issues/668
+if (get(ENV, "CI", nothing) != "true") && (get(ENV, "PARAVIEWCATALYST_DOC_DEFAULT_ENVIRONMENT", nothing) != "true")
+    push!(LOAD_PATH, paraviewcatalyst_root_dir)
+end
+
+using ParaViewCatalyst 
+
+# Define module-wide setups such that the respective modules are available in doctests
+DocMeta.setdocmeta!(ParaViewCatalyst, :DocTestSetup, :(using ParaViewCatalyst); recursive=true)
+
+# Copy some files from the top level directory to the docs and modify them
+# as necessary
+open(joinpath(@__DIR__, "src", "index.md"), "w") do io
+    # Point to source file
+    println(io, """
+    ```@meta
+    EditURL = "https://github.com/trixi-framework/ParaViewCatalyst.jl/blob/main/README.md"
+    ```
+    """)
+    # Write the modified contents
+    for line in eachline(joinpath(paraviewcatalyst_root_dir, "README.md"))
+        line = replace(line, "[LICENSE.md](LICENSE.md)" => "[License](@ref)")
+        println(io, line)
+    end
+end
+
+open(joinpath(@__DIR__, "src", "license.md"), "w") do io
+    # Point to source file
+    println(io, """
+    ```@meta
+    EditURL = "https://github.com/trixi-framework/ParaViewCatalyst.jl/blob/main/LICENSE.md"
+    ```
+    """)
+    # Write the modified contents
+    println(io, "# License")
+    println(io, "")
+    for line in eachline(joinpath(paraviewcatalyst_root_dir, "LICENSE.md"))
+        println(io, "> ", line)
+    end
+end
+
+# Make documentation
+makedocs(
+    # Specify modules for which docstrings should be shown
+    modules = [ParaViewCatalyst],
+    # Set sitename to Trixi.jl
+    sitename="ParaViewCatalyst.jl",
+    # Provide additional formatting options
+    format = Documenter.HTML(
+        # Disable pretty URLs during manual testing
+        prettyurls = get(ENV, "CI", nothing) == "true",
+        # Set canonical URL to GitHub pages URL
+        canonical = "https://trixi-framework.github.io/ParaViewCatalyst.jl/stable"
+    ),
+    # Explicitly specify documentation structure
+    pages = [
+        "Home" => "index.md",
+        "API reference" => "reference.md",
+        "License" => "license.md"
+    ],
+)
+
+
+deploydocs(;
+    repo = "github.com/trixi-framework/ParaViewCatalyst.jl",
+    devbranch = "main",
+    push_preview = true
+)

docs/src/.gitignore

@@ -0,0 +1,2 @@
+index.md
+license.md

docs/src/reference.md

@@ -0,0 +1,9 @@
+# API reference
+
+```@meta
+CurrentModule = ParaViewCatalyst
+```
+
+```@autodocs
+Modules = [ParaViewCatalyst]
+```