Doc and tests overhaul

Author: gdalle

Diff for: .JuliaFormatter.toml

@@ -1,6 +1 @@
-always_for_in = true
-whitespace_typedefs = true
-whitespace_ops_in_indices = true
-remove_extra_newlines = true
-import_to_using = true
-short_to_long_function_def = true
+style = "blue"

Diff for: .gitignore

@@ -1,3 +1,4 @@
 Manifest.toml
 docs/build/
 .vscode/settings.json
+docs/src/tutorial

Diff for: Project.toml

@@ -1,6 +1,6 @@
 name = "MetaGraphsNext"
 uuid = "fa8bd995-216d-47f1-8a91-f3b68fbeb377"
-version = "0.4.0"
+version = "0.4.1"
 
 [deps]
 Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
@@ -12,8 +12,10 @@ JLD2 = "0.1.11, 0.2, 0.3, 0.4"
 julia = "1.6"
 
 [extras]
+Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+JuliaFormatter = "98e50ef6-434e-11e9-1051-2b60c6c9e899"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["Documenter", "Test"]
+test = ["Aqua", "Documenter", "JuliaFormatter", "Test"]

Diff for: README.md

@@ -1,7 +1,9 @@
-# MetaGraphsNext
+# MetaGraphsNext.jl
 
 [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://JuliaGraphs.github.io/MetaGraphsNext.jl/dev)
 [![Build Status](https://github.com/JuliaGraphs/MetaGraphsNext.jl/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/JuliaGraphs/MetaGraphsNext.jl/actions/workflows/test.yml?query=branch%3Amaster)
 [![CodeCov](https://codecov.io/gh/JuliaGraphs/MetaGraphsNext.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/JuliaGraphs/MetaGraphsNext.jl)
 
-Welcome to MetaGraphsNext, an experimental, type-stable replacement for [MetaGraphs](https://github.com/JuliaGraphs/MetaGraphs.jl). This package will let you store metadata on the vertices and edges of your graphs. Take a look at the [documentation](https://juliagraphs.org/MetaGraphsNext.jl/dev/) to learn more!
+Welcome to MetaGraphsNext.jl, a type-stable replacement for [MetaGraphs.jl](https://github.com/JuliaGraphs/MetaGraphs.jl). It allows you to create graphs with vertex and edge metadata, on which you can unleash the full power of the [Graphs.jl](https://github.com/JuliaGraphs/Graphs.jl) ecosystem.
+
+Take a look at the [documentation](https://juliagraphs.org/MetaGraphsNext.jl/dev/) to learn more!

Diff for: docs/Project.toml

@@ -1,3 +1,5 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
+MetaGraphsNext = "fa8bd995-216d-47f1-8a91-f3b68fbeb377"

Diff for: docs/make.jl

@@ -1,24 +1,58 @@
-using Documenter: deploydocs, HTML, makedocs
+using Documenter
+using Literate
 using MetaGraphsNext
 
-makedocs(
-    sitename = "MetaGraphsNext.jl",
-    modules = [MetaGraphsNext],
-    doctest = true,
-    format = HTML(;
-        prettyurls = get(ENV, "CI", "false") == "true",
-        canonical = "https://juliagraphs.org/MetaGraphsNext.jl/dev/",
-        assets = String[],
-    ),
-    pages = [
-        "Home" => "index.md",
-        "Tutorial" => [
-            "Basics" => "tutorial_basics.md",
-            "Graphs.jl interface" => "tutorial_graphs.md",
-            "Reading / writing" => "tutorial_files.md",
-        ],
-        "API reference" => "api.md",
+DocMeta.setdocmeta!(MetaGraphsNext, :DocTestSetup, :(using MetaGraphsNext); recursive=true)
+
+TUTORIAL_DIR_JL = joinpath(dirname(@__DIR__), "test", "tutorial")
+TUTORIAL_DIR_MD = joinpath(@__DIR__, "src", "tutorial")
+
+for file in readdir(TUTORIAL_DIR_MD)
+    rm(joinpath(TUTORIAL_DIR_MD, file))
+end
+
+for file in readdir(TUTORIAL_DIR_JL)
+    Literate.markdown(
+        joinpath(TUTORIAL_DIR_JL, file),
+        TUTORIAL_DIR_MD;
+        documenter=true,
+        flavor=Literate.DocumenterFlavor(),
+    )
+end
+
+function markdown_title(path)
+    title = "?"
+    open(path, "r") do file
+        for line in eachline(file)
+            if startswith(line, '#')
+                title = strip(line, [' ', '#'])
+                break
+            end
+        end
+    end
+    return String(title)
+end
+
+pages = [
+    "Home" => "index.md",
+    "Tutorial" => [
+        markdown_title(joinpath(TUTORIAL_DIR_MD, file)) => joinpath("tutorial", file)
+        for file in sort(readdir(TUTORIAL_DIR_MD))
     ],
+    "API reference" => "api.md",
+]
+
+makedocs(;
+    sitename="MetaGraphsNext.jl",
+    modules=[MetaGraphsNext],
+    doctest=true,
+    pages=pages,
+    format=Documenter.HTML(;
+        prettyurls=get(ENV, "CI", "false") == "true",
+        canonical="https://juliagraphs.org/MetaGraphsNext.jl/dev/",
+        assets=String[],
+        edit_link=:commit,
+    ),
 )
 
-deploydocs(repo = "github.com/JuliaGraphs/MetaGraphsNext.jl.git")
+deploydocs(; repo="github.com/JuliaGraphs/MetaGraphsNext.jl.git")

Diff for: docs/src/api.md

@@ -6,8 +6,20 @@
 Modules = [MetaGraphsNext]
 ```
 
+```@docs
+haskey
+getindex
+setindex!
+delete!
+```
+
+```@docs
+add_vertex!
+add_edge!
+weights
+```
+
 ## Index
 
 ```@index
-Modules = [MetaGraphsNext]
-```
+```

Diff for: docs/src/index.md

@@ -1,6 +1,6 @@
 # MetaGraphsNext.jl
 
-Welcome to `MetaGraphsNext.jl`, an experimental, type-stable replacement for [MetaGraphs](https://github.com/JuliaGraphs/MetaGraphs.jl).
+Welcome to MetaGraphsNext.jl, a type-stable replacement for [MetaGraphs.jl](https://github.com/JuliaGraphs/MetaGraphs.jl). It allows you to create graphs with vertex and edge metadata, on which you can unleash the full power of the [Graphs.jl](https://github.com/JuliaGraphs/Graphs.jl) ecosystem.
 
 ## Getting started
 
@@ -9,5 +9,3 @@ To install the package, open the Julia REPL and type
 ```julia
 julia> using Pkg; Pkg.add("MetaGraphsNext")
 ```
-
-The tutorial provides an overview of the functionalities. We first explain the [basics](tutorial_basics.md) of the `MetaGraph` structure, before moving on to its [integration](tutorial_graphs.md) with `Graphs.jl`.