set up template for docs

.github/workflows/Documenter.yml

@@ -0,0 +1,64 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - 'main'
+    tags: '*'
+    paths-ignore:
+      - '.zenodo.json'
+      - '.github/workflows/benchmark.yml'
+      - '.github/workflows/ci.yml'
+      - '.github/workflows/CompatHelper.yml'
+      - '.github/workflows/TagBot.yml'
+      - 'benchmark/**'
+      - 'utils/**'
+  pull_request:
+    paths-ignore:
+      - '.zenodo.json'
+      - '.github/workflows/benchmark.yml'
+      - '.github/workflows/ci.yml'
+      - '.github/workflows/CompatHelper.yml'
+      - '.github/workflows/TagBot.yml'
+      - 'benchmark/**'
+      - 'utils/**'
+  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@v4
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: '1'
+          show-versioninfo: true
+      - uses: actions/cache@v3
+        env:
+          cache-name: cache-artifacts
+        with:
+          path: ~/.julia/artifacts
+          key: ${{ runner.os }}-test-${{ env.cache-name }}-${{ hashFiles('**/Project.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-test-${{ env.cache-name }}-
+            ${{ runner.os }}-test-
+            ${{ runner.os }}-
+      - uses: julia-actions/julia-buildpkg@v1
+        env:
+          PYTHON: ""
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+        env:
+          PYTHON: ""
+      - name: Build and deploy documentation
+        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" # https://discourse.julialang.org/t/generation-of-documentation-fails-qt-qpa-xcb-could-not-connect-to-display/60988
+          PYTHON: ""
+        run: julia --project=docs --color=yes docs/make.jl

CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing
+
+PositiveIntegrators.jl is an open-source project and we are very happy
+to accept contributions from the community. Please feel free to open issues
+or submit patches (preferably as pull requests) any time. For planned larger
+contributions, it is often beneficial to get in contact first, for example via
+issues.
+
+PositiveIntegrators.jl and its contributions are licensed under the
+MIT license (see [LICENSE.md](LICENSE.md)). As a contributor, you certify
+that all your contributions are in conformance with the *Developer Certificate
+of Origin (Version 1.1)*, which is reproduced below.
+
+## Developer Certificate of Origin (Version 1.1)
+The following text was taken from
+[https://developercertificate.org](https://developercertificate.org):
+
+    Developer Certificate of Origin
+    Version 1.1
+
+    Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+    1 Letterman Drive
+    Suite D4700
+    San Francisco, CA, 94129
+
+    Everyone is permitted to copy and distribute verbatim copies of this
+    license document, but changing it is not allowed.
+
+
+    Developer's Certificate of Origin 1.1
+
+    By making a contribution to this project, I certify that:
+
+    (a) The contribution was created in whole or in part by me and I
+        have the right to submit it under the open source license
+        indicated in the file; or
+
+    (b) The contribution is based upon previous work that, to the best
+        of my knowledge, is covered under an appropriate open source
+        license and I have the right under that license to submit that
+        work with modifications, whether created in whole or in part
+        by me, under the same open source license (unless I am
+        permitted to submit under a different license), as indicated
+        in the file; or
+
+    (c) The contribution was provided directly to me by some other
+        person who certified (a), (b) or (c) and I have not modified
+        it.
+
+    (d) I understand and agree that this project and the contribution
+        are public and that a record of the contribution (including all
+        personal information I submit with it, including my sign-off) is
+        maintained indefinitely and may be redistributed consistent with
+        this project or the open source license(s) involved.

docs/make.jl

@@ -0,0 +1,75 @@
+using Documenter
+using Pkg: Pkg
+using PositiveIntegrators
+
+# Define module-wide setups such that the respective modules are available in doctests
+DocMeta.setdocmeta!(PositiveIntegrators,
+  :DocTestSetup, :(using PositiveIntegrators); recursive=true)
+
+# Copy some files from the top level directory to the docs and modify them
+# as necessary
+open(joinpath(@__DIR__, "src", "license.md"), "w") do io
+  # Point to source license file
+  println(io, """
+  ```@meta
+  EditURL = "https://github.com/SKopecz/PositiveIntegrators.jl/blob/main/LICENSE.md"
+  ```
+  """)
+  # Write the modified contents
+  println(io, "# License")
+  println(io, "")
+  for line in eachline(joinpath(dirname(@__DIR__), "LICENSE.md"))
+    line = replace(line, "[LICENSE.md](LICENSE.md)" => "[License](@ref)")
+    println(io, "> ", line)
+  end
+end
+
+open(joinpath(@__DIR__, "src", "contributing.md"), "w") do io
+  # Point to source license file
+  println(io, """
+  ```@meta
+  EditURL = "https://github.com/SKopecz/PositiveIntegrators.jl/blob/main/CONTRIBUTING.md"
+  ```
+  """)
+  # Write the modified contents
+  println(io, "# Contributing")
+  println(io, "")
+  for line in eachline(joinpath(dirname(@__DIR__), "CONTRIBUTING.md"))
+    line = replace(line, "[LICENSE.md](LICENSE.md)" => "[License](@ref)")
+    println(io, "> ", line)
+  end
+end
+
+# Make documentation
+makedocs(
+  modules = [PositiveIntegrators],
+  sitename="PositiveIntegrators.jl",
+  format = Documenter.HTML(
+    prettyurls = get(ENV, "CI", nothing) == "true",
+    canonical = "https://SKopecz.github.io/PositiveIntegrators.jl/stable"
+  ),
+  # Explicitly specify documentation structure
+  pages = [
+    "Home" => "index.md",
+    "Introduction" => "introduction.md",
+    "Tutorials" => [
+      "tutorials/constant_linear_advection.md",
+      "tutorials/advection_diffusion.md",
+      "tutorials/variable_linear_advection.md",
+      "tutorials/wave_equation.md",
+      "tutorials/kdv.md",
+    ],
+    "Automatic differentiation (AD)" => "ad.md",
+    "Applications & references" => "applications.md",
+    "Benchmarks" => "benchmarks.md",
+    "API reference" => "api_reference.md",
+    "Contributing" => "contributing.md",
+    "License" => "license.md"
+  ]
+)
+
+deploydocs(
+  repo = "github.com/SKopecz/PositiveIntegrators.jl",
+  devbranch = "main",
+  push_preview = true
+)

docs/src/index.md

@@ -0,0 +1,59 @@
+# PositiveIntegrators.jl
+
+The [Julia]() library
+[PositiveIntegrators.jl](https://github.com/ranocha/PositiveIntegrators.jl)
+provides several time integration methods developed to preserve the positivity
+of numerical solutions.
+
+TODO: More introduction etc.
+
+
+## Installation
+
+TODO: PositiveIntegrators.jl has to be registered - up to now, it is not!
+
+[PositiveIntegrators.jl](https://github.com/SKopecz/PositiveIntegrators.jl)
+is a registered Julia package. Thus, you can install it from the Julia REPL via
+```julia
+julia> using Pkg; Pkg.add("PositiveIntegrators")
+```
+
+If you want to update PositiveIntegrators.jl, you can use
+```julia
+julia> using Pkg; Pkg.update("PositiveIntegrators")
+```
+As usual, if you want to update PositiveIntegrators.jl and all other
+packages in your current project, you can execute
+```julia
+julia> using Pkg; Pkg.update()
+```
+
+
+## Basic examples
+
+TODO
+
+
+## Referencing
+
+If you use
+[PositiveIntegrators.jl](https://github.com/ranocha/PositiveIntegrators.jl)
+for your research, please cite it using the bibtex entry
+```bibtex
+@misc{PositiveIntegrators.jl,
+  title={{PositiveIntegrators.jl}: {A} {J}ulia library of positivity-perserving
+         time integration methods},
+  author={Kopecz, Stefan and Ranocha, Hendrik and contributors},
+  year={2023},
+  doi={TODO},
+  url={https://github.com/SKopecz/PositiveIntegrators.jl}
+}
+```
+
+
+## License and contributing
+
+This project is licensed under the MIT license (see [License](@ref)).
+Since it is an open-source project, we are very happy to accept contributions
+from the community. Please refer to the section [Contributing](@ref) for more
+details.