Add Documenter

.github/workflows/DocPreviewCleanup.yml

@@ -0,0 +1,32 @@
+name: Doc Preview Cleanup
+
+on:
+  pull_request:
+    types: [closed]
+
+jobs:
+  doc-preview-cleanup:
+    # Do not run on forks to avoid authorization errors
+    # Source: https://github.community/t/have-github-action-only-run-on-master-repo-and-not-on-forks/140840/18
+    if: github.repository_owner == 'trixi-framework'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout gh-pages branch
+        uses: actions/checkout@v3
+        with:
+          ref: gh-pages
+
+      - name: Delete preview and history
+        shell: bash
+        run: |
+            git config user.name "Documenter.jl"
+            git config user.email "[email protected]"
+            git rm -rf --ignore-unmatch "previews/PR$PRNUM"
+            git commit -m "delete preview" --allow-empty
+            git branch gh-pages-new $(echo "delete history" | git commit-tree HEAD^{tree})
+        env:
+            PRNUM: ${{ github.event.number }}
+
+      - name: Push changes
+        run: |
+            git push --force origin gh-pages-new:gh-pages

.github/workflows/Documenter.yml

@@ -0,0 +1,47 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - 'main'
+    tags: '*'
+    paths-ignore:
+      - '.zenodo.json'
+      - '.github/workflows/ci.yml'
+      - '.github/workflows/CompatHelper.yml'
+      - '.github/workflows/TagBot.yml'
+  pull_request:
+    paths-ignore:
+      - '.zenodo.json'
+      - '.github/workflows/ci.yml'
+      - '.github/workflows/CompatHelper.yml'
+      - '.github/workflows/TagBot.yml'
+  workflow_dispatch:
+
+# Cancel redundant CI tests automatically
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: '1.9'
+          show-versioninfo: true
+      - uses: julia-actions/julia-buildpkg@v1
+        with:
+          project: 'LibTrixi.jl'
+        env:
+          PYTHON: ""
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=joinpath(pwd(), "LibTrixi.jl"))); Pkg.instantiate()'
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
+          GKSwstype: 100 # To make GitHub Action work, disable showing a plot window with the GR backend of the Plots package
+        run: julia --project=docs --color=yes docs/make.jl

.gitignore

@@ -10,3 +10,6 @@ cmake_install.cmake
 libtrixi.mod
 libtrixi.so*
 fortran_hello_world
+
+# Documenter
+docs/build

LibTrixi.jl/.gitignore

@@ -1 +1,2 @@
+Manifest.toml
 run

LibTrixi.jl/src/api_c.jl

@@ -3,7 +3,7 @@
     trixi_initialize(libelixir::AbstractString)::Cint
 
 Initialize a new simulation based on the file `libelixir`and return a handle to the
-corresponding [`simulationstate`](@ref) as a `Cint` (i.e, a plain C `int`).
+corresponding [`SimulationState`](@ref) as a `Cint` (i.e, a plain C `int`).
 
 The libelixir has a similar purpose as a regular "elixir" in Trixi.jl, as it completely
 defines a simulation setup in Julia code. A key difference (and thus the name libelixir) is

LibTrixi.jl/src/simulationstate.jl

@@ -1,5 +1,9 @@
-# Struct to store a simulation state that consists of a semidiscretization plus the time
-# integrator
+"""
+    SimulationState
+
+Data structure to store a simulation state that consists of a semidiscretization
+plus the time integrator.
+"""
 mutable struct SimulationState{SemiType, IntegratorType}
     semi::SemiType
     integrator::IntegratorType

README.md

@@ -1,6 +1,9 @@
 # libtrixi
 
-Interface library for using Trixi.jl from C/C++/Fortran.
+[![Docs-dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://trixi-framework.github.io/libtrixi/dev)
+[![License: MIT](https://img.shields.io/badge/License-MIT-success.svg)](https://opensource.org/licenses/MIT)
+
+**Libtrixi** is an interface library for using Trixi.jl from C/C++/Fortran.
 
 **Note: This project is in a very early stage and subject to changes without warning at any time.**
 
@@ -73,3 +76,20 @@ are also its principal maintainers.
 
 ## License
 Libtrixi is licensed under the MIT license (see [LICENSE.md](LICENSE.md)).
+
+## Acknowledgments
+<p align="center">
+  <!-- DFG -->
+  <img align="middle" src="https://user-images.githubusercontent.com/3637659/231429826-31fd7e78-19b4-4bac-8d4c-d292c6570d93.jpg" height="100" />
+  <!-- BMBF -->
+  <img align="middle" src="https://user-images.githubusercontent.com/3637659/231436391-b28a76a4-f027-40f9-bd28-14e3a2f3e16a.png" height="100" />
+</p>
+
+This project has benefited from funding by the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation)
+through the research unit FOR 5409 "Structure-Preserving Numerical Methods for Bulk- and
+Interface Coupling of Heterogeneous Models (SNuBIC)" (project number 463312734).
+
+This project has benefited from funding from the German Federal Ministry of
+Education and Research through the project grant "Adaptive earth system modeling
+with significantly reduced computation time for exascale supercomputers
+(ADAPTEX)" (funding id: 16ME0668K).

docs/Project.toml

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

docs/make.jl

@@ -0,0 +1,45 @@
+using Documenter
+import Pkg
+
+# Get LibTrixi.jl root directory
+libtrixi_root_dir = dirname(@__DIR__)
+
+# Fix for https://github.com/trixi-framework/Trixi.jl/issues/668
+if (get(ENV, "CI", nothing) != "true") && (get(ENV, "TRIXI_DOC_DEFAULT_ENVIRONMENT", nothing) != "true")
+    push!(LOAD_PATH, libtrixi_root_dir)
+end
+
+using LibTrixi
+
+# Define module-wide setups such that the respective modules are available in doctests
+DocMeta.setdocmeta!(LibTrixi, :DocTestSetup, :(using LibTrixi); recursive=true)
+
+# Make documentation
+makedocs(
+    # Specify modules for which docstrings should be shown
+    modules = [LibTrixi],
+    # Set sitename to Trixi.jl
+    sitename="Libtrixi",
+    # 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/libtrixi/stable"
+    ),
+    # Explicitly specify documentation structure
+    pages = [
+        "Home" => "index.md",
+        "Reference" => [
+                        "LibTrixi.jl" => "reference-libtrixi-jl.md",
+                       ],
+        "License" => "license.md"
+    ],
+    strict = true # to make the GitHub action fail when doctests fail, see https://github.com/neuropsychology/Psycho.jl/issues/34
+)
+
+deploydocs(
+    repo = "github.com/trixi-framework/libtrixi",
+    devbranch = "main",
+    push_preview = true
+)

docs/src/index.md

@@ -0,0 +1,88 @@
+# libtrixi
+
+[![Docs-dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://trixi-framework.github.io/libtrixi/dev)
+[![License: MIT](https://img.shields.io/badge/License-MIT-success.svg)](https://opensource.org/licenses/MIT)
+
+**Libtrixi** is an interface library for using Trixi.jl from C/C++/Fortran.
+
+**Note: This project is in a very early stage and subject to changes without warning at any time.**
+
+## Getting started
+
+### Prerequisites
+
+A local installation of `MPI` and `Julia` is required.
+
+### Get the sources
+
+```bash
+git clone [email protected]:trixi-framework/libtrixi.git
+```
+
+### Building
+
+For building, `cmake` and its typical workflow is used.
+
+1. It is recommended to created an out-of-source build directory, e.g.
+
+    ```bash
+    mkdir build
+    cd build
+    ```
+
+2. Call cmake
+
+    ```bash
+    cmake -DCMAKE_INSTALL_PREFIX=<install_directory> ..
+    ```
+
+    `cmake` should find `MPI` and `Julia` automatically. If not, the directories
+    can be specified manually.
+    The `cmake` clients `ccmake` or `cmake-gui` could be useful.
+
+    Specifying the directory `install_directory` for later installation is optional.
+
+3. Call make
+
+    ```bash
+    make
+    ```
+
+    This will build and place `libtrixi.so` in the current directory along with its
+    header and a Fortran `mod` file. Your application will have to include and link
+    against these.
+
+    Examples can be found in the `examples` subdirectory.
+
+4. Install (optional)
+
+    ```bash
+    make install
+    ```
+
+    This will install all provided file to the specified location.
+
+### Testing
+
+Check out the `fortran_hello_world` example.
+
+## Authors
+Libtrixi was initiated by
+[Benedict Geihe](https://www.mi.uni-koeln.de/NumSim/)
+(University of Cologne, Germany) and
+[Michael Schlottke-Lakemper](https://lakemper.eu)
+(RWTH Aachen University/High-Performance Computing Center Stuttgart (HLRS), Germany), who
+are also its principal maintainers.
+
+## [License](@id readme-license)
+Libtrixi is licensed under the MIT license (see [License](@ref)).
+
+## Acknowledgments
+This project has benefited from funding by the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation)
+through the research unit FOR 5409 "Structure-Preserving Numerical Methods for Bulk- and
+Interface Coupling of Heterogeneous Models (SNuBIC)" (project number 463312734).
+
+This project has benefited from funding from the German Federal Ministry of
+Education and Research through the project grant "Adaptive earth system modeling
+with significantly reduced computation time for exascale supercomputers
+(ADAPTEX)" (funding id: 16ME0668K).

docs/src/license.md

@@ -0,0 +1,23 @@
+# License
+
+> MIT License
+> 
+> Copyright (c) 2023 Benedict Geihe and Michael Schlottke-Lakemper
+> 
+> Permission is hereby granted, free of charge, to any person obtaining a copy
+> of this software and associated documentation files (the "Software"), to deal
+> in the Software without restriction, including without limitation the rights
+> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+> copies of the Software, and to permit persons to whom the Software is
+> furnished to do so, subject to the following conditions:
+> 
+> The above copyright notice and this permission notice shall be included in all
+> copies or substantial portions of the Software.
+> 
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+> SOFTWARE.

docs/src/reference-libtrixi-jl.md

@@ -0,0 +1,9 @@
+# LibTrixi.jl API
+
+```@meta
+CurrentModule = LibTrixi
+```
+
+```@autodocs
+Modules = [LibTrixi]
+```