From d5ea0e8d610ec45de7791c438efd08924c12fa4b Mon Sep 17 00:00:00 2001 From: Hendrik Ranocha Date: Fri, 20 Oct 2023 16:59:36 +0200 Subject: [PATCH] set up template for docs --- .github/workflows/Documenter.yml | 64 +++++++++++++++++++++++++++ CONTRIBUTING.md | 54 +++++++++++++++++++++++ docs/make.jl | 75 ++++++++++++++++++++++++++++++++ docs/src/index.md | 59 +++++++++++++++++++++++++ 4 files changed, 252 insertions(+) create mode 100644 .github/workflows/Documenter.yml create mode 100644 CONTRIBUTING.md create mode 100644 docs/make.jl create mode 100644 docs/src/index.md diff --git a/.github/workflows/Documenter.yml b/.github/workflows/Documenter.yml new file mode 100644 index 00000000..82dc61e3 --- /dev/null +++ b/.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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..71ddffb6 --- /dev/null +++ b/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. diff --git a/docs/make.jl b/docs/make.jl new file mode 100644 index 00000000..9ffd0d9d --- /dev/null +++ b/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 +) diff --git a/docs/src/index.md b/docs/src/index.md new file mode 100644 index 00000000..ed88d498 --- /dev/null +++ b/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.