Setup most dummy files.

.github/workflows/CompatHelper.yml

@@ -0,0 +1,25 @@
+name: CompatHelper
+on:
+  schedule:
+    - cron: 0 0 * * *
+  workflow_dispatch:
+jobs:
+  CompatHelper:
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Install CompatHelper"
+        run: |
+          import Pkg
+          name = "CompatHelper"
+          uuid = "21be47e3-92bf-4199-8515-27870869dcc6"
+          version = "3"
+          Pkg.add(; name, uuid, version)
+        shell: julia --color=yes {0}
+      - name: "Run CompatHelper"
+        run: |
+          using CompatHelper
+          CompatHelper.main(; subdirs = ["", "docs", "examples"])
+        shell: julia --color=yes {0}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          COMPATHELPER_PRIV: ${{ secrets.DOCUMENTER_KEY }}

.github/workflows/TagBot.yml

@@ -0,0 +1,31 @@
+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 }}
+          ssh: ${{ secrets.DOCUMENTER_KEY }}

.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+on:
+  push:
+    branches: [master]
+    tags: [v*]
+  pull_request:
+
+jobs:
+  test:
+    name: Julia ${{ matrix.julia-version }} - ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        julia-version: ["1.6", "1.10"]
+        os: [ubuntu-latest, macOS-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: ${{ matrix.julia-version }}
+          arch: x64
+      - uses: julia-actions/cache@v1
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-runtest@v1
+      - uses: julia-actions/julia-processcoverage@v1
+      - uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          file: ./lcov.info
+          name: codecov-umbrella
+          fail_ci_if_error: false
+        if: ${{ matrix.os =='ubuntu-latest' }}

.github/workflows/clear_preview.yml

@@ -0,0 +1,26 @@
+name: Doc Preview Cleanup
+
+on:
+  pull_request:
+    types: [closed]
+
+jobs:
+  doc-preview-cleanup:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout gh-pages branch
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+      - name: Delete preview and history + push changes
+        run: |
+            if [ -d "previews/PR$PRNUM" ]; then
+              git config user.name "Documenter.jl"
+              git config user.email "[email protected]"
+              git rm -rf "previews/PR$PRNUM"
+              git commit -m "delete preview"
+              git branch gh-pages-new $(echo "delete history" | git commit-tree HEAD^{tree})
+              git push --force origin gh-pages-new:gh-pages
+            fi
+        env:
+            PRNUM: ${{ github.event.number }}

.github/workflows/documenter.yml

@@ -0,0 +1,56 @@
+name: Documenter
+on:
+  push:
+    branches: [master]
+    tags: [v*]
+  pull_request:
+
+jobs:
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: quarto-dev/quarto-actions/setup@v2
+        with:
+          version: "1.3.353"
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: "1.10"
+      - name: Julia Cache
+        uses: julia-actions/cache@v1
+      - name: Cache Quarto
+        id: cache-quarto
+        uses: actions/cache@v4
+        env:
+          cache-name: cache-quarto
+        with:
+          path: tutorials/_freeze
+          key: ${{ runner.os }}-${{ env.cache-name }}-${{ hashFiles('tutorials/*.qmd') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ env.cache-name }}-
+      - name: Cache Documenter
+        id: cache-documenter
+        uses: actions/cache@v4
+        env:
+          cache-name: cache-documenter
+        with:
+          path: docs/src/tutorials
+          key: ${{ runner.os }}-${{ env.cache-name }}-${{ hashFiles('tutorials/*.qmd') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ env.cache-name }}-
+      - name: Cache CondaPkg
+        id: cache-condaPkg
+        uses: actions/cache@v4
+        env:
+          cache-name: cache-condapkg
+        with:
+          path: docs/.CondaPkg
+          key: ${{ runner.os }}-${{ env.cache-name }}-${{ hashFiles('docs/CondaPkg.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ env.cache-name }}-
+      - name: "Documenter rendering (including Quarto)"
+        run: "docs/make.jl --quarto --prettyurls"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}

.github/workflows/format.yml

@@ -0,0 +1,29 @@
+name: Format
+on:
+  push:
+    branches: [master]
+    tags: [v*]
+  pull_request:
+
+jobs:
+  format:
+    name: "Format Check"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: 1
+      - name: Install JuliaFormatter and format
+        run: |
+          using Pkg
+          Pkg.add(PackageSpec(name="JuliaFormatter"))
+          using JuliaFormatter
+          format("."; verbose=true)
+        shell: julia --color=yes {0}
+      - name: Suggest formatting changes
+        uses: reviewdog/action-suggester@v1
+        if: github.event_name == 'pull_request'
+        with:
+          tool_name: JuliaFormatter
+          fail_on_error: true

.gitignore

@@ -0,0 +1,2 @@
+docs/Manifest.toml
+examples/Manifest.toml

CONTRIBUTING.md

@@ -0,0 +1,65 @@
+# Contributing to `ManifoldExamples.jl`
+
+First, thanks for taking the time to contribute.
+Any contribution is appreciated and welcome.
+
+The following is a set of guidelines to [`ManifoldExamples.jl`](https://juliamanifolds.github.io/ManifoldExamples.jl/).
+
+#### Table of Contents
+
+- [Contributing to `ManifoldExamples.jl`](#contributing-to-manifoldexamplesjl)
+      - [Table of Contents](#table-of-contents)
+  - [I just have a question](#i-just-have-a-question)
+  - [How can I file an issue?](#how-can-i-file-an-issue)
+  - [How can I contribute?](#how-can-i-contribute)
+    - [Add an example](#add-an-example)
+  - [Code style](#code-style)
+
+## I just have a question
+
+The developer can most easily be reached in the Julia Slack channel [#manifolds](https://julialang.slack.com/archives/CP4QF0K5Z).
+You can apply for the Julia Slack workspace [here](https://julialang.org/slack/) if you haven't joined yet.
+You can also ask your question on [our GitHub discussion](https://github.com/JuliaManifolds/ManoptExamples.jl/discussions).
+
+## How can I file an issue?
+
+If you found a bug or want to propose a feature, we track our issues within the [GitHub repository](https://github.com/JuliaManifolds/ManoptExamples.jl/issues).
+
+## How can I contribute?
+
+### Add an example
+
+If you have used one of the problems from here in an example or you are providing a problem
+together with an example, please add a corresponding [Quarto](https://quarto.org) Markdown file to the `examples/`
+folder. The Markdown file should provide a short introduction to the problem and provide links
+to further details, maybe a paper or a preprint. Use the `bib/literature.yaml` file to add
+references (in `CSL_YAML`, which can for example be exported e.g. from Zotero).
+
+Add any packages you need to the `examples/` environment (see the containting `Project.toml`).
+The examples will not be run on CI, but their rendered `CommonMark` outpout should be included
+in the list of examples in the documentation of this package.
+
+## Code style
+
+We try to follow the [documentation guidelines](https://docs.julialang.org/en/v1/manual/documentation/)
+from the Julia documentation as well as [Blue Style](https://github.com/invenia/BlueStyle).
+We run [`JuliaFormatter.jl`](https://github.com/domluna/JuliaFormatter.jl) on the repo in
+the way set in the `.JuliaFormatter.toml` file, which enforces a number of conventions consistent with the Blue Style.
+
+We also follow a few internal conventions:
+
+- Any implemented function should be accompanied by its mathematical formulae if a closed
+  form exists.
+- within a file the structs should come first and functions second. The only exception
+  are constructors for the structs
+- within both blocks an alphabetical order is preferable.
+- The above implies that the mutating variant of a function follows the non-mutating variant.
+- There should be no dangling `=` signs.
+- Always add a newline between things of different types (struct/method/const).
+- Always add a newline between methods for different functions (including in-place/non-mutating variants).
+- Prefer to have no newline between methods for the same function; when reasonable,
+  merge the docstrings into a generic function signature.
+- All `import`/`using`/`include` should be in the main module file.
+- There should only be a minimum of `export`s within this file, all problems should usually
+  be later addressed as `ManifoldExamples.[...]`
+- the Quarto Markdown files are excluded from this formatting.

docs/Project.toml

@@ -0,0 +1,4 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
+DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"

docs/index.md

@@ -0,0 +1,3 @@
+# ManifoldExamples.jl
+
+Examples working with `Manifolds.jl`.

docs/make.jl

@@ -0,0 +1,64 @@
+#!/usr/bin/env julia
+#
+#
+
+#
+# (a) if docs is not the current active environment, switch to it
+# (from https://github.com/JuliaIO/HDF5.jl/pull/1020/) 
+if Base.active_project() != joinpath(@__DIR__, "Project.toml")
+    using Pkg
+    Pkg.activate(@__DIR__)
+    Pkg.develop(PackageSpec(; path=(@__DIR__) * "/../"))
+    Pkg.resolve()
+    Pkg.instantiate()
+end
+
+# (b) Did someone say render? Then we render!
+if "--quarto" ∈ ARGS
+    using CondaPkg
+    CondaPkg.withenv() do
+        @info "Rendering Quarto"
+        examples_folder = (@__DIR__) * "/../examples"
+        # instantiate the tutorials environment if necessary
+        Pkg.activate(examples_folder)
+        Pkg.resolve()
+        Pkg.instantiate()
+        Pkg.build("IJulia") # build IJulia to the right version.
+        Pkg.activate(@__DIR__) # but return to the docs one before
+        run(`quarto render $(examples_folder)`)
+    end
+end
+
+# (c) load necessary packages for the docs
+using Documenter: DocMeta, HTML, MathJax3, deploydocs, makedocs
+using ManifoldExamples
+
+generated_path = joinpath(@__DIR__, "src")
+base_url = "https://github.com/JuliaManifolds/ManifoldExamples.jl/blob/master/"
+isdir(generated_path) || mkdir(generated_path)
+open(joinpath(generated_path, "contributing.md"), "w") do io
+    # Point to source license file
+    println(
+        io,
+        """
+        ```@meta
+        EditURL = "$(base_url)CONTRIBUTING.md"
+        ```
+        """,
+    )
+    # Write the contents out below the meta block
+    for line in eachline(joinpath(dirname(@__DIR__), "CONTRIBUTING.md"))
+        println(io, line)
+    end
+end
+
+makedocs(;
+    format=HTML(; mathengine=MathJax3(), prettyurls=get(ENV, "CI", nothing) == "true"),
+    sitename="ManifoldExamples.jl",
+    modules=[ManifoldExamples],
+    pages=[
+        "Home" => "index.md",
+        "Contributing to ManifoldExamples.jl" => "contributing.md",
+    ],
+)
+deploydocs(; repo="github.com/JuliaManifolds/ManifoldExamples.jl", push_preview=true)

examples/Project.toml

@@ -0,0 +1,2 @@
+[deps]
+ManifoldExamples = "21be47e3-92bf-4199-8515-27870869dcc6"

examples/_quarto.yml

@@ -0,0 +1,28 @@
+
+project:
+  title: "ManifoldExamples.jl"
+  output-dir: ../docs/src/examples
+  render:
+    - "*.qmd"
+
+crossref:
+  fig-prefix: Figure
+  tbl-prefix: Table
+# bibliography:
+#   - ../CITATION.bib
+#   - ../bib/literature.yaml
+# csl: ../bib/journal-of-the-royal-statistical-society.csl
+fig-format: png
+
+execute:
+  freeze: auto
+  eval: true
+  echo: true
+  output: true
+
+format:
+  commonmark:
+    variant: -raw_html+tex_math_dollars
+    wrap: preserve
+
+jupyter: "julia-1.10"

test/runtest.jl

@@ -0,0 +1,5 @@
+using ManifoldExamples, Test
+
+@testset "Manifold Examples" begin
+
+end