[WIP] Setup initial documentation

.gitignore

@@ -13,6 +13,9 @@
 **/Manifest.toml
 out*/
 docs/build
+docs/src/authors.md
+docs/src/code_of_conduct.md
+docs/src/contributing.md
 public/
 coverage/
 coverage_report/

AUTHORS.md

@@ -0,0 +1,22 @@
+# Authors
+
+TrixiShallowWater.jl's development is coordinated by a group of *principal developers*,
+who are also its main contributors and who can be contacted in case of
+questions about TrixiShallowWater.jl. In addition, there are *contributors* who have
+provided substantial additions or modifications. Together, these two groups form
+"The TrixiShallowWater.jl Authors" as mentioned in the [LICENSE.md](LICENSE.md) file.
+
+## Principal Developers
+* [Andrew Winters](https://liu.se/en/employee/andwi94),
+  Linköping University, Sweden
+* [Patrick Ersing](https://liu.se/en/employee/pater53),
+  Linköping University, Sweden
+
+## Contributors
+The following people contributed major additions or modifications to TrixiShallowWater.jl and
+are listed in alphabetical order:
+
+* Patrick Ersing
+* Hendrik Ranocha
+* Michael Schlottke-Lakemper
+* Andrew Winters

CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the principal developers responsible for enforcement listed in
+[AUTHORS.md](AUTHORS.md).
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing
+
+TrixiShallowWater.jl is an open-source project and we are very happy to accept contributions
+from the community. Please feel free to
+[open issues](https://github.com/trixi-framework/TrixiShallowWater.jl/issues/new/choose)
+or submit patches (preferably as
+[pull requests](https://github.com/trixi-framework/TrixiShallowWater.jl/pulls))
+any time. For planned larger contributions, it is often beneficial to get
+in contact with one of the principal developers first (see
+[AUTHORS.md](AUTHORS.md)).
+
+TrixiShallowWater.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.

LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023-present The Trixi.jl Authors (see [trixi-framework/Trixi.jl/AUTHORS.md](https://github.com/trixi-framework/Trixi.jl/blob/main/AUTHORS.md))
+Copyright (c) 2023-present The TrixiShallowWater.jl Authors (see [trixi-framework/TrixiShallowWater.jl/AUTHORS.md](https://github.com/trixi-framework/TrixiShallowWater.jl/blob/main/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  

README.md

@@ -2,9 +2,84 @@
 
 [![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://trixi-framework.github.io/TrixiShallowWater.jl/stable/)
 [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://trixi-framework.github.io/TrixiShallowWater.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/TrixiShallowWater.jl/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/trixi-framework/TrixiShallowWater.jl/actions/workflows/ci.yml?query=branch%3Amain)
 [![Coverage](https://codecov.io/gh/trixi-framework/TrixiShallowWater.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/trixi-framework/TrixiShallowWater.jl)
 [![Coverage](https://coveralls.io/repos/github/trixi-framework/TrixiShallowWater.jl/badge.svg?branch=main)](https://coveralls.io/github/trixi-framework/TrixiShallowWater.jl?branch=main)
+[![License: MIT](https://img.shields.io/badge/License-MIT-success.svg)](https://opensource.org/licenses/MIT)
+
+<p align="center">
+  <img width="300px" src="https://trixi-framework.github.io/assets/logo_sw.png">
+</p>
+
+**TrixiShallowWater.jl** is a numerical simulation package focused on solving shallow water equations
+with the discontinuous Galerkin method and written in Julia. The package builds on the numerical
+simulation framework for conservation laws [Trixi.jl](https://github.com/trixi-framework/Trixi.jl)
+and provides several specialized models and features specific for shallow water applications.
+Below is a short summary of the available features:
+
+* 1D and 2D simulations on [line/quad meshes](https://trixi-framework.github.io/Trixi.jl/stable/overview/#Semidiscretizations)
+  * Cartesian and curvilinear meshes
+  * Conforming and non-conforming meshes
+  * Hierarchical quadtree meshes with adaptive mesh refinement
+* High-order accuracy in space and time
+  * Entropy-stable discontinuous Galerkin methods based on flux differencing
+  * Entropy-stable shock capturing
+  * Positivity-preserving limiting
+  * Compatible with the [SciML ecosystem for ordinary differential equations](https://diffeq.sciml.ai/latest/)
+  * CFL-based and error-based time step control
+* Shallow water capabilities
+  * Wetting and drying
+  * Multi-layer flows
+  * Sediment transport via an Exner model
+
+## Examples
+
+## Installation
+If you have not yet installed Julia, please [follow the instructions for your
+operating system](https://julialang.org/downloads/platform/). TrixiShallowWater.jl works
+with Julia v1.8 and newer. We recommend using the latest stable release of Julia.
+
+[comment]: <> (We can update this with a "for users" and "for developers" section once the package is registered)
+
+TrixiShallowWater.jl is **not** a registered Julia package, and therefore needs to be downloaded manually and then run from with the cloned directory:
+```bash
+git clone https://github.com/trixi-framework/TrixiShallowWater.jl.git
+julia --project=@.
+```
+In addition TrixiShallowWater.jl requires the numerical solver framework [Trixi.jl](https://github.com/trixi-framework/Trixi.jl), [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl) for time integration, and [Plots.jl](https://github.com/JuliaPlots/Plots.jl) for visualization, which can be installed by executing the following in the Julia REPL:
+```julia
+julia> using Pkg
+
+julia> Pkg.add(["Trixi", "Trixi2Vtk", "OrdinaryDiffEq", "Plots"])
+```
+
+## Authors
+TrixiShallowWater.jl is maintained by the
+[Trixi authors](https://github.com/trixi-framework/Trixi.jl/blob/main/AUTHORS.md).
+Its principal developers are [Andrew Winters](https://liu.se/en/employee/andwi94)
+(Linköping University, Sweden)
+and [Patrick Ersing](https://liu.se/en/employee/pater53)
+(Linköping University, Sweden).
+The full list of contributors can be found in [AUTHORS.md](AUTHORS.md).
+
+## License and contributing
+TrixiShallowWater.jl is licensed under the MIT license (see [LICENSE.md](LICENSE.md)).
+Since TrixiShallowWater.jl is an open-source project, we are very happy to accept contributions from the
+community. 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/TrixiShallowWater.jl/issues/new).
+
+## Acknowledgments
+<p align="center" style="font-size:0;"><!--
+  SRC      --><img align="middle" src="https://github.com/trixi-framework/Trixi.jl/assets/3637659/48f9da06-6f7a-4586-b23e-739bee3901c0" height="120"><!--
+  -->
+</p>
+
+This project has benefited from funding from [Vetenskapsrådet](https://www.vr.se)
+(VR, Swedish Research Council), Sweden
+through the VR Starting Grant "Shallow water flows including sediment transport and morphodynamics",
+VR grant agreement 2020-03642 VR.
 
 **Note: This repository is still in its alpha stage and anything might change at
 any time and without warning, including the deletion of this repository

docs/make.jl

@@ -6,9 +6,51 @@ using DocumenterInterLinks
 links = InterLinks("Trixi" => ("https://trixi-framework.github.io/Trixi.jl/stable/",
                                "https://trixi-framework.github.io/Trixi.jl/stable/objects.inv"))
 
+# Copy list of authors to not need to synchronize it manually
+authors_text = read(joinpath(dirname(@__DIR__), "AUTHORS.md"), String)
+authors_text = replace(authors_text,
+                       "in the [LICENSE.md](LICENSE.md) file" => "under [License](@ref)")
+write(joinpath(@__DIR__, "src", "authors.md"), authors_text)
+
 DocMeta.setdocmeta!(TrixiShallowWater, :DocTestSetup, :(using TrixiShallowWater);
                     recursive = true)
 
+# Copy some files from the repository root directory to the docs and modify them
+# as necessary
+# Based on: https://github.com/ranocha/SummationByPartsOperators.jl/blob/0206a74140d5c6eb9921ca5021cb7bf2da1a306d/docs/make.jl#L27-L41
+open(joinpath(@__DIR__, "src", "code_of_conduct.md"), "w") do io
+    # Point to source license file
+    println(io,
+            """
+            ```@meta
+            EditURL = "https://github.com/trixi-framework/TrixiShallowWater.jl/blob/main/CODE_OF_CONDUCT.md"
+            ```
+            """)
+    # Write the modified contents
+    println(io, "# [Code of Conduct](@id code-of-conduct)")
+    println(io, "")
+    for line in eachline(joinpath(dirname(@__DIR__), "CODE_OF_CONDUCT.md"))
+        line = replace(line, "[AUTHORS.md](AUTHORS.md)" => "[Authors](@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/trixi-framework/TrixiTrixiShallowWater.jl/blob/main/CONTRIBUTING.md"
+            ```
+            """)
+    # Write the modified contents
+    for line in eachline(joinpath(dirname(@__DIR__), "CONTRIBUTING.md"))
+        line = replace(line, "[LICENSE.md](LICENSE.md)" => "[License](@ref)")
+        line = replace(line, "[AUTHORS.md](AUTHORS.md)" => "[Authors](@ref)")
+        println(io, line)
+    end
+end
+
 makedocs(;
          modules = [TrixiShallowWater],
          authors = "Andrew R. Winters <[email protected]>, Michael Schlottke-Lakemper <[email protected]>",
@@ -21,6 +63,14 @@ makedocs(;
                                   assets = String[],),
          pages = [
              "Home" => "index.md",
+             "Installation" => "installation.md",
+             "Tutorials" => "tutorial.md",
+             "Advanced topics & developers" => ["Development" => "development.md"
+                                                "Testing" => "testing.md"],
+             "Authors" => "authors.md",
+             "Contributing" => "contributing.md",
+             "Code of Conduct" => "code_of_conduct.md",
+             "License" => "license.md",
          ],
          plugins = [links],)