From 9b672ebee58a8d2b4276b162ee1240a75d958d5f Mon Sep 17 00:00:00 2001 From: Michael Schlottke-Lakemper Date: Thu, 28 Nov 2024 10:06:31 +0100 Subject: [PATCH] Add basic Documenter workflow (#6) * Add basic Documenter workflow * renamed to LICENSE.md * Readme updates * Make header unique * assign different id to license section in doc/index.md * small additions * Revert "assign different id to license section in doc/index.md" This reverts commit 74de7a7fd495edddeb0b9b3555cd58a949e7e84a. * typo --------- Co-authored-by: Benedict Geihe --- .github/workflows/Documenter.yml | 46 ++++++++++++++++++++ LICENSE => LICENSE.md | 0 README.md | 45 ++++++++++++++------ docs/.gitignore | 1 + docs/Project.toml | 5 +++ docs/make.jl | 73 ++++++++++++++++++++++++++++++++ docs/src/.gitignore | 2 + docs/src/reference.md | 9 ++++ 8 files changed, 169 insertions(+), 12 deletions(-) create mode 100644 .github/workflows/Documenter.yml rename LICENSE => LICENSE.md (100%) create mode 100644 docs/.gitignore create mode 100644 docs/Project.toml create mode 100644 docs/make.jl create mode 100644 docs/src/.gitignore create mode 100644 docs/src/reference.md diff --git a/.github/workflows/Documenter.yml b/.github/workflows/Documenter.yml new file mode 100644 index 0000000..2eb325c --- /dev/null +++ b/.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 diff --git a/LICENSE b/LICENSE.md similarity index 100% rename from LICENSE rename to LICENSE.md diff --git a/README.md b/README.md index da4211e..10ee0d4 100644 --- a/README.md +++ b/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-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) +[![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= @@ -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). diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..567609b --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +build/ diff --git a/docs/Project.toml b/docs/Project.toml new file mode 100644 index 0000000..1814eb3 --- /dev/null +++ b/docs/Project.toml @@ -0,0 +1,5 @@ +[deps] +Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" + +[compat] +Documenter = "1" diff --git a/docs/make.jl b/docs/make.jl new file mode 100644 index 0000000..6fa121f --- /dev/null +++ b/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 +) diff --git a/docs/src/.gitignore b/docs/src/.gitignore new file mode 100644 index 0000000..312f831 --- /dev/null +++ b/docs/src/.gitignore @@ -0,0 +1,2 @@ +index.md +license.md diff --git a/docs/src/reference.md b/docs/src/reference.md new file mode 100644 index 0000000..8652843 --- /dev/null +++ b/docs/src/reference.md @@ -0,0 +1,9 @@ +# API reference + +```@meta +CurrentModule = ParaViewCatalyst +``` + +```@autodocs +Modules = [ParaViewCatalyst] +```