Initial development (#1)

* Add some default CI scripts and .gitignore * Make it a Julia package * Add basic testing infrastructure * Fix tests * Fix coverage analysis * Add docs * Update docs/make.jl Co-authored-by: Hendrik Ranocha <[email protected]> * Update .github/workflows/ci.yml * Revise existing files * Add JuliaFormatter config * Fix docs * Add `trixi_include` * Reformat * Make tests work for Julia 1.8 * Fill authors file * Update .github/workflows/ci.yml * Remove duplicate version * Remove message * Run CI on latest Julia version * Fix CI * Reformat * Fix tests * Reformat * Try to fix CI on Windows * Hopefully fix CI on Windows * Fix CI * Come on, Windows * Update .github/workflows/ci.yml * Disable format check on Windows and macOS * Oops * Update .github/workflows/Documenter.yml Co-authored-by: Hendrik Ranocha <[email protected]> * Update README.md Co-authored-by: Hendrik Ranocha <[email protected]> * Update docs/src/index.md Co-authored-by: Hendrik Ranocha <[email protected]> * Update README.md Co-authored-by: Michael Schlottke-Lakemper <[email protected]> * Update docs/make.jl Co-authored-by: Michael Schlottke-Lakemper <[email protected]> * Update src/trixi_include.jl Co-authored-by: Michael Schlottke-Lakemper <[email protected]> * Update src/trixi_include.jl Co-authored-by: Michael Schlottke-Lakemper <[email protected]> * Remove `index.md` * Properly build landing page * Docs landing page --------- Co-authored-by: Hendrik Ranocha <[email protected]> Co-authored-by: Erik Faulhaber <[email protected]>
trixi-framework · Jan 29, 2024 · bf6528a · bf6528a
1 parent e3497d4
commit bf6528a
Show file tree

Hide file tree

Showing 21 changed files with 663 additions and 1 deletion.
diff --git a/.JuliaFormatter.toml b/.JuliaFormatter.toml
@@ -0,0 +1,14 @@
+# Use SciML style: https://github.com/SciML/SciMLStyle
+style = "sciml"
+
+# Python style alignment. See https://github.com/domluna/JuliaFormatter.jl/pull/732.
+yas_style_nesting = true
+
+# Align struct fields for better readability of large struct definitions
+align_struct_field = true
+
+# No whitespaces in kwargs because this is more common in Julia
+whitespace_in_kwargs = false
+
+# Allow Dict definitions to be aligned like arrays. See https://github.com/domluna/JuliaFormatter.jl/pull/676
+variable_call_indent = ["Dict"]
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -0,0 +1,7 @@
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "monthly"
diff --git a/.github/workflows/CompatHelper.yml b/.github/workflows/CompatHelper.yml
@@ -0,0 +1,45 @@
+name: CompatHelper
+on:
+  schedule:
+    - cron: 0 0 * * *
+  workflow_dispatch:
+permissions:
+  contents: write
+  pull-requests: write
+jobs:
+  CompatHelper:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check if Julia is already available in the PATH
+        id: julia_in_path
+        run: which julia
+        continue-on-error: true
+      - name: Install Julia, but only if it is not already available in the PATH
+        uses: julia-actions/setup-julia@v1
+        with:
+          version: '1'
+          arch: ${{ runner.arch }}
+        if: steps.julia_in_path.outcome != 'success'
+      - name: "Add the General registry via Git"
+        run: |
+          import Pkg
+          ENV["JULIA_PKG_SERVER"] = ""
+          Pkg.Registry.add("General")
+        shell: julia --color=yes {0}
+      - name: "Install CompatHelper"
+        run: |
+          import Pkg
+          name = "CompatHelper"
+          uuid = "aa819f21-2bde-4658-8897-bab36330d9b7"
+          version = "3"
+          Pkg.add(; name, uuid, version)
+        shell: julia --color=yes {0}
+      - name: "Run CompatHelper"
+        run: |
+          import CompatHelper
+          CompatHelper.main(; subdirs=["", "test", "docs"])
+        shell: julia --color=yes {0}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          COMPATHELPER_PRIV: ${{ secrets.DOCUMENTER_KEY }}
+          # COMPATHELPER_PRIV: ${{ secrets.COMPATHELPER_PRIV }}
diff --git a/.github/workflows/Documenter.yml b/.github/workflows/Documenter.yml
@@ -0,0 +1,45 @@
+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:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out project
+        uses: actions/checkout@v4
+      - name: Set up Julia
+        uses: julia-actions/setup-julia@v1
+        with:
+          version: '1'
+          show-versioninfo: true
+      - uses: julia-actions/cache@v1
+      - name: Build package
+        uses: julia-actions/julia-buildpkg@v1
+      - 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/.github/workflows/SpellCheck.yml b/.github/workflows/SpellCheck.yml
@@ -0,0 +1,13 @@
+name: Spell Check
+
+on: [pull_request, workflow_dispatch]
+
+jobs:
+  typos-check:
+    name: Spell Check with Typos
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Actions Repository
+        uses: actions/checkout@v4
+      - name: Check spelling
+        uses: crate-ci/[email protected]
diff --git a/.github/workflows/TagBot.yml b/.github/workflows/TagBot.yml
@@ -0,0 +1,33 @@
+name: TagBot
+on:
+  issue_comment:
+    types:
+      - created
+  workflow_dispatch:
+    inputs:
+      lookback:
+        default: 3
+permissions:
+  actions: read
+  checks: read
+  contents: write
+  deployments: read
+  issues: read
+  discussions: read
+  packages: read
+  pages: read
+  pull-requests: read
+  repository-projects: read
+  security-events: read
+  statuses: read
+jobs:
+  TagBot:
+    if: github.event_name == 'workflow_dispatch' || github.actor == 'JuliaTagBot'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: JuliaRegistries/TagBot@v1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          # Edit the following line to reflect the actual name of the GitHub Secret containing your private key
+          ssh: ${{ secrets.DOCUMENTER_KEY }}
+          # ssh: ${{ secrets.NAME_OF_MY_SSH_PRIVATE_KEY_SECRET }}
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,89 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+    tags: ['*']
+    paths-ignore:
+      - 'CITATION.bib'
+      - 'LICENSE.md'
+      - 'README.md'
+      - '.zenodo.json'
+      - '.github/workflows/CompatHelper.yml'
+      - '.github/workflows/SpellCheck.yml'
+      - '.github/workflows/TagBot.yml'
+      - 'docs/**'
+  pull_request:
+    paths-ignore:
+      - 'CITATION.bib'
+      - 'LICENSE.md'
+      - 'README.md'
+      - '.zenodo.json'
+      - '.github/workflows/CompatHelper.yml'
+      - '.github/workflows/SpellCheck.yml'
+      - '.github/workflows/TagBot.yml'
+      - 'docs/**'
+  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:
+  test:
+    name: ${{ matrix.os }} - Julia ${{ matrix.version }} - ${{ github.event_name }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        version:
+          - '1.8'
+          - '1.9'
+          - '1'
+        os:
+          - ubuntu-latest
+          - macOS-latest
+          - windows-latest
+    steps:
+      - name: Check out project
+        uses: actions/checkout@v4
+      - name: Set up Julia
+        uses: julia-actions/setup-julia@v1
+        with:
+          version: ${{ matrix.version }}
+      - run: julia -e 'using InteractiveUtils; versioninfo(verbose=true)'
+      - uses: julia-actions/cache@v1
+      - name: Apply JuliaFormatter and check format
+        if: matrix.os == 'ubuntu-latest'
+        run: |
+          julia -e 'using Pkg; Pkg.add("JuliaFormatter")'
+          julia -e 'using JuliaFormatter; !format(".", verbose=true) &&
+            error("Code not properly formatted")'
+      - name: Build package
+        uses: julia-actions/julia-buildpkg@v1
+      - name: Run tests
+        uses: julia-actions/julia-runtest@v1
+        with:
+          coverage: true
+      - name: Process coverage results
+        uses: julia-actions/julia-processcoverage@v1
+        with:
+          directories: src,test
+      - name: Upload coverage report to Codecov
+        uses: codecov/codecov-action@v3
+        with:
+          files: lcov.info
+          token: ${{ secrets.CODECOV_TOKEN }}
+      - name: Upload coverage report to Coveralls
+        uses: coverallsapp/github-action@master
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          path-to-lcov: ./lcov.info
+      # Enable tmate debugging of manually-triggered workflows if the input option was provided
+      - name: Setup tmate session for debugging
+        if: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.debug_enabled && always() }}
+        uses: mxschmitt/action-tmate@v3
+        timeout-minutes: 15
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,15 @@
+Manifest.toml
+docs/build
+docs/src/index.md
+docs/src/authors.md
+docs/src/license.md
+public/
+coverage/
+coverage_report/
+*.jl.*.cov
+.vscode/
+run
+
+.DS_Store
+
+LocalPreferences.toml
diff --git a/AUTHORS.md b/AUTHORS.md
@@ -0,0 +1,8 @@
+# Authors
+
+This package is maintained by the authors of
+[Trixi.jl](https://github.com/trixi-framework/Trixi.jl).
+For a full list of authors, see
+[AUTHORS.md](https://github.com/trixi-framework/Trixi.jl/blob/main/AUTHORS.md)
+in the Trixi.jl repository.
+These authors form "The Trixi.jl Authors", as mentioned in the [LICENSE.md](LICENSE.md) file.
diff --git a/LICENSE.md b/LICENSE.md
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020-present The Trixi.jl Authors (see [AUTHORS.md](AUTHORS.md))
+
+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.
diff --git a/Project.toml b/Project.toml
@@ -0,0 +1,4 @@
+name = "TrixiBase"
+uuid = "9a0f1c46-06d5-4909-a5a3-ce25d3fa3284"
+authors = ["Michael Schlottke-Lakemper <[email protected]>"]
+version = "0.1.0"
diff --git a/README.md b/README.md
@@ -1,2 +1,11 @@
 # TrixiBase.jl
-Common functionality used by multiple Julia packages in the Trixi Framework
+
+[![Docs-stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://trixi-framework.github.io/TrixiBase.jl/stable)
+[![Docs-dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://trixi-framework.github.io/TrixiBase.jl/dev)
+[![Build Status](https://github.com/trixi-framework/TrixiBase.jl/workflows/CI/badge.svg)](https://github.com/trixi-framework/TrixiBase.jl/actions?query=workflow%3ACI)
+[![Coveralls](https://coveralls.io/repos/github/trixi-framework/TrixiBase.jl/badge.svg)](https://coveralls.io/github/trixi-framework/TrixiBase.jl)
+[![Codecov](https://codecov.io/gh/trixi-framework/TrixiBase.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/trixi-framework/TrixiBase.jl)
+[![License: MIT](https://img.shields.io/badge/License-MIT-success.svg)](https://opensource.org/license/mit/)
+
+TrixiBase.jl provides common functionality used by multiple Julia packages in the
+[Trixi Framework](https://github.com/trixi-framework).
diff --git a/docs/Project.toml 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
@@ -0,0 +1,59 @@
+using Documenter
+
+# Get TrixiBase.jl root directory
+trixibase_root_dir = dirname(@__DIR__)
+
+# Fix for https://github.com/trixi-framework/Trixi.jl/issues/668
+if (get(ENV, "CI", nothing) != "true") &&
+   (get(ENV, "TRIXIBASE_DOC_DEFAULT_ENVIRONMENT", nothing) != "true")
+    push!(LOAD_PATH, trixibase_root_dir)
+end
+
+using TrixiBase
+
+# Define module-wide setups such that the respective modules are available in doctests
+DocMeta.setdocmeta!(TrixiBase, :DocTestSetup, :(using TrixiBase); recursive=true)
+
+# Copy files to not need to synchronize them manually
+function copy_file(filename, replaces...; new_filename=lowercase(filename))
+    content = read(joinpath(trixibase_root_dir, filename), String)
+    content = replace(content, replaces...)
+
+    header = """
+    ```@meta
+    EditURL = "https://github.com/trixi-framework/TrixiBase.jl/blob/main/$filename"
+    ```
+    """
+    content = header * content
+
+    write(joinpath(@__DIR__, "src", new_filename), content)
+end
+
+copy_file("README.md", new_filename="index.md")
+copy_file("AUTHORS.md",
+          "in the [LICENSE.md](LICENSE.md) file" => "under [License](@ref)")
+# Add section `# License` and add `>` in each line to add a quote
+copy_file("LICENSE.md",
+          "[AUTHORS.md](AUTHORS.md)" => "[Authors](@ref)",
+          "\n" => "\n> ", r"^" => "# License\n\n> ")
+
+# Make documentation
+makedocs(sitename="TrixiBase.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/TrixiBase.jl/stable"),
+         # Explicitly specify documentation structure
+         pages=[
+             "Home" => "index.md",
+             "API reference" => "reference.md",
+             "Authors" => "authors.md",
+             "License" => "license.md",
+         ])
+
+deploydocs(;
+           repo="github.com/trixi-framework/TrixiBase.jl",
+           devbranch="main",
+           push_preview=true)
diff --git a/docs/src/reference.md b/docs/src/reference.md
@@ -0,0 +1,9 @@
+# API reference
+
+```@meta
+CurrentModule = TrixiBase
+```
+
+```@autodocs
+Modules = [TrixiBase]
+```