Refactor ManifoldsBase to a two-level dispatch design

.github/workflows/documenter.yml

@@ -0,0 +1,29 @@
+name: Documenter
+on:
+  push:
+    branches: [master]
+    tags: [v*]
+  pull_request:
+
+jobs:
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    if: "contains( github.event.pull_request.labels.*.name, 'preview docs') || github.ref == 'refs/heads/master' || contains(github.ref, 'refs/tags/')"
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: 1.7
+      - uses: julia-actions/julia-docdeploy@v1
+        env:
+          PYTHON: ""
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
+  note:
+    name: "Documentation deployment note."
+    runs-on: ubuntu-latest
+    if: "!contains( github.event.pull_request.labels.*.name, 'preview docs')"
+    steps:
+      - name: echo instructions
+        run: echo 'The Documentation is only generated and pushed on a PR if the “preview docs” label is added.'

.gitignore

@@ -4,3 +4,4 @@
 deps/deps.jl
 
 Manifest.toml
+docs/build

Readme.md

@@ -0,0 +1,30 @@
+# ManifoldsBase.jl
+[![](https://img.shields.io/badge/docs-stable-blue.svg)](https://juliamanifolds.github.io/Manifolds.jl/stable/interface.html)
+[![](https://img.shields.io/badge/docs-dev-blue.svg)](https://juliamanifolds.github.io/Manifolds.jl/latest/interface.html)
+[![Build Status](https://travis-ci.org/JuliaManifolds/ManifoldsBase.jl.svg?branch=master)](https://travis-ci.org/JuliaManifolds/ManifoldsBase.jl/)
+[![codecov.io](http://codecov.io/github/JuliaManifolds/ManifoldsBase.jl/coverage.svg?branch=master)](https://codecov.io/gh/JuliaManifolds/ManifoldsBase.jl/)
+[![arXiv](https://img.shields.io/badge/arXiv%20CS.MS-2106.08777-blue.svg)](https://arxiv.org/abs/2106.08777)
+
+## Installation
+
+In Julia you can install this package by typing
+
+```julia
+] add Manopt
+```
+
+in the Julia REPL.
+
+## Citation
+
+If you use `ManifoldsBase.jl` in your work, please cite the following
+
+```biblatex
+@online{2106.08777,
+Author = {Seth D. Axen and Mateusz Baran and Ronny Bergmann and Krzysztof Rzecki},
+Title = {Manifolds.jl: An Extensible Julia Framework for Data Analysis on Manifolds},
+Year = {2021},
+Eprint = {2106.08777},
+Eprinttype = {arXiv},
+}
+```

docs/Project.toml

@@ -0,0 +1,7 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+ManifoldsBase = "3362f125-f0bb-47a3-aa74-596ffd7ef2fb"
+
+[compat]
+Documenter = "0.24"
+ManifoldsBase = "0.12"

docs/make.jl

@@ -0,0 +1,19 @@
+using ManifoldsBase, Documenter
+
+makedocs(
+    format = Documenter.HTML(prettyurls = false, assets = ["assets/favicon.ico"]),
+    modules = [ManifoldsBase],
+    authors = "Seth Axen, Mateusz Baran, Ronny Bergmann, and contributors.",
+    sitename = "ManifoldsBase.jl",
+    pages = [
+        "Home" => "index.md",
+        "How to write a manifold" => "example.md",
+        "Design principles" => "design.md",
+        "The manifold" => "manifold.md",
+        "Basic functions" => "functions.md",
+        "Meta manifolds" => "metamanifolds.md",
+        "Extending Manifolds" => "decorator.md",
+        "Bases for tangent spaces" => "bases.md",
+    ],
+)
+deploydocs(repo = "github.com/JuliaManifolds/ManifoldsBase.jl.git", push_preview = true)

docs/src/assets/site.webmanifest

@@ -0,0 +1,19 @@
+{
+    "name": "",
+    "short_name": "",
+    "icons": [
+        {
+            "src": "/android-chrome-192x192.png",
+            "sizes": "192x192",
+            "type": "image/png"
+        },
+        {
+            "src": "/android-chrome-512x512.png",
+            "sizes": "512x512",
+            "type": "image/png"
+        }
+    ],
+    "theme_color": "#ffffff",
+    "background_color": "#ffffff",
+    "display": "standalone"
+}

docs/src/bases.md

@@ -0,0 +1,33 @@
+# Bases for tangent spaces
+
+The following functions and types provide support for bases of the tangent space of different manifolds.
+Moreover, bases of the cotangent space are also supported, though this description focuses on the tangent space.
+An orthonormal basis of the tangent space ``T_p \mathcal M`` of (real) dimension ``n`` has a real-coefficient basis ``e_1, e_2, …, e_n`` if ``\mathrm{Re}(g_p(e_i, e_j)) = δ_{ij}`` for each ``i,j ∈ \{1, 2, …, n\}`` where ``g_p`` is the Riemannian metric at point ``p``.
+A vector ``X`` from the tangent space ``T_p \mathcal M`` can be expressed in Einstein notation as a sum ``X = X^i e_i``, where (real) coefficients ``X^i`` are calculated as ``X^i = \mathrm{Re}(g_p(X, e_i))``.
+
+The main types are:
+
+* [`DefaultOrthonormalBasis`](@ref), which is designed to work when no special properties of the tangent space basis are required.
+   It is designed to make [`get_coordinates`](@ref) and [`get_vector`](@ref) fast.
+* [`DiagonalizingOrthonormalBasis`](@ref), which diagonalizes the curvature tensor and makes the curvature in the selected direction equal to 0.
+* [`ProjectedOrthonormalBasis`](@ref), which projects a basis of the ambient space and orthonormalizes projections to obtain a basis in a generic way.
+* [`CachedBasis`](@ref), which stores (explicitly or implicitly) a precomputed basis at a certain point.
+
+The main functions are:
+
+* [`get_basis`](@ref) precomputes a basis at a certain point.
+* [`get_coordinates`](@ref) returns coordinates of a tangent vector.
+* [`get_vector`](@ref) returns a vector for the specified coordinates.
+* [`get_vectors`](@ref) returns a vector of basis vectors. Calling it should be avoided for high-dimensional manifolds.
+
+```@autodocs
+Modules = [ManifoldsBase]
+Pages = ["bases.jl"]
+Order = [:type, :function]
+```
+
+```@autodocs
+Modules = [ManifoldsBase]
+Pages = ["vector_spaces.jl"]
+Order = [:type, :function]
+```

docs/src/decorator.md

@@ -0,0 +1,23 @@
+# A Decorator for manifolds
+
+A decorator manifold extends the functionality of a [`AbstractManifold`](@ref) in a semi-transparent way.
+It internally stores the [`AbstractManifold`](@ref) it extends and by default for functions defined in `ManifoldsBase.jl` it acts transparently in the sense that it passes all functions through to the base except those that it actually affects.
+For example, because the [`ValidationManifold`](@ref) affects nearly all functions, it overwrites nearly all functions, except a few like [`manifold_dimension`](@ref).
+
+By default, i.e. for a plain new decorator, all functions are transparent, i.e. passed down to the manifold the [`AbstractDecoratorManifold`](@ref) decorates.
+To implement a method for a decorator that behaves differently from the method of the same function for the internal manifold, two steps are required.
+Let's assume the function is called `f(M, arg1, arg2)`, and our decorator manifold `DM` of type `OurDecoratorManifold` decorates `M`.
+Then
+
+1. set `decorator_transparent_dispatch(f, M::OurDecoratorManifold, args...) = Val(:intransparent)`
+2. implement `f(DM::OurDecoratorManifold, arg1, arg2)`
+
+This makes it possible to extend a manifold or all manifolds with a feature or replace a feature of the original manifold.
+
+A final technical note – if several manifolds have similar transparency rules concerning functions from the interface, the last parameter `T` of the [`AbstractDecoratorManifold`](@ref)`{𝔽,T<:`[`AbstractDecoratorType`](@ref)`}` can be used to dispatch on different transparency schemes.
+
+```@autodocs
+Modules = [ManifoldsBase]
+Pages = ["DecoratorManifold.jl"]
+Order = [:type, :macro, :function]
+```