Merge pull request #23 from gdalle/master

Harmonize code and improve docs

Project.toml

@@ -1,18 +1,19 @@
 name = "MetaGraphsNext"
 uuid = "fa8bd995-216d-47f1-8a91-f3b68fbeb377"
-version = "0.2"
+version = "0.2.0"
 
 [deps]
-JLD2 = "033835bb-8acc-5ee8-8aae-3f567f8a3819"
 Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
+JLD2 = "033835bb-8acc-5ee8-8aae-3f567f8a3819"
 
 [compat]
-JLD2 = "0.1.11, 0.2, 0.3, 0.4"
 Graphs = "1.4.1"
+JLD2 = "0.1.11, 0.2, 0.3, 0.4"
 julia = "1"
 
 [extras]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["Documenter"]
+test = ["Documenter", "Test"]

README.md

@@ -1,10 +1,7 @@
 # MetaGraphsNext
 
 [![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.jl`, an experimental, type-stable replacement for [MetaGraphs](https://github.com/JuliaGraphs/MetaGraphs.jl).
-
-## Getting started
-
-To see how the package works, take a look at the tutorial in the [documentation](https://juliagraphs.org/MetaGraphsNext.jl/dev/). We first explain [the basics](tutorial_basics.md) of the `MetaGraph` structure, before moving on to its [integration](tutorial_graphs.md) with `Graphs.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!

docs/Project.toml

@@ -1,2 +1,3 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"

docs/src/api.md

@@ -1,42 +1,13 @@
 # API reference
 
-## Basics
+## Docstrings
 
 ```@autodocs
 Modules = [MetaGraphsNext]
-Pages = ["metagraph.jl"]
 ```
 
-```@autodocs
-Modules = [MetaGraphsNext]
-Pages = ["metaundigraph.jl", "metadigraph.jl"]
-```
-
-```@autodocs
-Modules = [MetaGraphsNext]
-Pages = ["dict_utils.jl"]
-```
-
-```@autodocs
-Modules = [MetaGraphsNext]
-Pages = ["weights.jl"]
-```
+## Index
 
-## Graphs.jl interface
-
-```@autodocs
-Modules = [MetaGraphsNext]
-Pages = ["graphs.jl"]
-```
-
-```@autodocs
-Modules = [MetaGraphsNext]
-Pages = ["overrides.jl"]
-```
-
-## Reading / writing
-
-```@autodocs
+```@index
 Modules = [MetaGraphsNext]
-Pages = ["persistence.jl"]
 ```

docs/src/index.md

@@ -4,10 +4,10 @@ Welcome to `MetaGraphsNext.jl`, an experimental, type-stable replacement for [Me
 
 ## Getting started
 
-To see how the package works, take a look at the tutorial. We first explain [the basics](tutorial_basics.md) of the `MetaGraph` structure, before moving on to its [integration](tutorial_graphs.md) with `Graphs.jl`.
+To install the package, open the Julia REPL and type
 
-## Index
-
-```@index
-Modules = [MetaGraphsNext]
+```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`.

docs/src/tutorial_basics.md

@@ -11,127 +11,133 @@ julia> using MetaGraphsNext
 We provide a default constructor in which you only need to specify types:
 
 ```jldoctest example
-julia> colors = MetaGraph(Graph(), VertexMeta = String, EdgeMeta = Symbol, gprops = "special")
-Meta graph based on a {0, 0} undirected simple Int64 graph with vertices indexed by Symbol(s), String(s) vertex metadata, Symbol(s) edge metadata, "special" as graph metadata, and default weight 1.0
+julia> colors = MetaGraph( Graph(), VertexData = String, EdgeData = Symbol, graph_data = "graph_of_colors")
+Meta graph based on a {0, 0} undirected simple Int64 graph with vertex labels of type Symbol, vertex metadata of type String, edge metadata of type Symbol, graph metadata given by "graph_of_colors", and default weight 1.0
 ```
 
-## Adding and modifying vertices
+## Modifying the graph
 
-Use `setindex!` (as you would do with a dictionary) to add a new vertex with the given metadata. If a vertex with the given label does not exist, it will be created automatically. Otherwise, `setindex!` will modify the metadata for the existing vertex.
+Modifications of graph elements and the associated metadata can always be done using `setindex!` (as in a dictionary) with the relevant labels.
+
+### Vertices
+
+Use `setindex!` with one key to add a new vertex with the given label and metadata. If a vertex with the given label does not exist, it will be created automatically. Otherwise, the function will simply modify the metadata for the existing vertex.
 
 ```jldoctest example
 julia> colors[:red] = "warm";
 
 julia> colors[:yellow] = "warm";
 
+julia> colors[:blue] = "warm";  # wrong metadata
+
 julia> colors[:blue] = "cool";
 ```
 
-## Using vertex codes
+### Edges
 
-In the absence of removal, vertex codes correspond to order of insertion in the underlying graph:
+Use `setindex!` with two keys to add a new edge between the given labels and containing the given metadata. Beware that this time, nonexistent labels will throw an error.
 
 ```jldoctest example
-julia> code_for(colors, :red)
-1
+julia> colors[:red, :yellow] = :orange;
 
-julia> code_for(colors, :blue)
-3
+julia> colors[:red, :blue] = :violet;
+
+julia> colors[:yellow, :blue] = :green;
 ```
 
-You can retrieve the associated labels as follows:
+## Accessing graph properties
+
+To retrieve graph properties, we still follow a dictionary-like interface based on labels.
+
+### Existence
+
+To check the presence of a vertex or edge, use `haskey`:
 
 ```jldoctest example
-julia> label_for(colors, 1)
-:red
+julia> haskey(colors, :red)
+true
 
-julia> label_for(colors, 3)
-:blue
+julia> haskey(colors, :black)
+false
+
+julia> haskey(colors, :red, :yellow) && haskey(colors, :yellow, :red)
+true
+
+julia> haskey(colors, :red, :black)
+false
 ```
 
-## Accessing metadata
+### Metadata
 
-You can access and change the metadata using indexing: zero arguments for graph metadata, one label for vertex metadata, and two labels for edge metadata.
+All kinds of metadata can be accessed with `getindex`:
 
 ```jldoctest example
 julia> colors[]
-"special"
-
-julia> colors[:blue] = "very cool";
+"graph_of_colors"
 
 julia> colors[:blue]
-"very cool"
+"cool"
 
-julia> colors[:red, :yellow] = :orange;
-
-julia> colors[:red, :yellow]
-:orange
+julia> colors[:yellow, :blue]
+:green
 ```
 
-Checking the presence of a vertex or edge can be done with `haskey`:
-
-```jldoctest example
-julia> haskey(colors, :red)
-true
-
-julia> haskey(colors, :green)
-false
+## Using vertex codes
 
-julia> haskey(colors, :red, :yellow)
-true
+In the absence of removal, vertex codes correspond to order of insertion in the underlying graph:
 
-julia> haskey(colors, :yellow, :red) # undirected graph, so vertex order doesn't matter
-true
+```jldoctest example
+julia> code_for(colors, :red)
+1
 
-julia> haskey(colors, :red, :green)
-false
+julia> code_for(colors, :blue)
+3
 ```
 
-## Deleting vertices and edges
-
-You can delete vertices and edges with `delete!`.
+You can retrieve the associated labels as follows:
 
 ```jldoctest example
-julia> delete!(colors, :red, :yellow);
+julia> label_for(colors, 1)
+:red
 
-julia> delete!(colors, :blue);
+julia> label_for(colors, 3)
+:blue
 ```
 
 ## Adding weights
 
 The most simple way to add edge weights is to speficy a default weight for all of them.
 
 ```jldoctest example
-julia> defaultweight(MetaGraph(Graph(), defaultweight = 2))
+julia> weighted_default = MetaGraph(Graph(), default_weight = 2);
+
+julia> default_weight(weighted_default)
 2
 
-julia> weighttype(MetaGraph(Graph(), defaultweight = 2))
+julia> weighttype(weighted_default)
 Int64
 ```
 
-You can use the `weightfunction` keyword to specify a function which will
-transform edge metadata into a weight. This weight must always be the same
-type as the `defaultweight`.
+You can use the `weight_function` keyword to specify a function which will transform edge metadata into a weight. This weight must always be the same type as the `default_weight`.
 
 ```jldoctest example
-julia> weighted = MetaGraph(Graph(), EdgeMeta = Float64, weightfunction = identity);
+julia> weighted = MetaGraph(Graph(), EdgeData = Float64, weight_function = identity);
 
 julia> weighted[:red] = nothing; weighted[:blue] = nothing; weighted[:yellow] = nothing;
 
 julia> weighted[:red, :blue] = 1.0; weighted[:blue, :yellow] = 2.0;
 
-julia> the_weights = Graphs.weights(weighted)
-metaweights
+julia> weight_matrix = Graphs.weights(weighted)
+MetaWeights of size (3, 3)
 
-julia> size(the_weights)
+julia> size(weight_matrix)
 (3, 3)
 
-julia> the_weights[1, 3]
+julia> weight_matrix[1, 3]
 1.0
 
-julia> diameter(weighted)
-3.0
-
-julia> weightfunction(weighted)(0)
+julia> weight_function(weighted)(0)
 0
-```
+```
+
+You can then use all functions from Graphs.jl that require weighted graphs (see the rest of the tutorial).

docs/src/tutorial_files.md

@@ -24,9 +24,9 @@ graph T {
 }
 
 julia> complicated = MetaGraph(DiGraph(),
-            VertexMeta = Dict{Symbol, Int},
-            EdgeMeta = Dict{Symbol, Int},
-            gprops = (tagged = true,)
+            VertexData = Dict{Symbol, Int},
+            EdgeData = Dict{Symbol, Int},
+            graph_data = (tagged = true,)
         );
 
 julia> complicated[:a] = Dict(:code_1 => 1, :code_2 => 2);
@@ -57,4 +57,4 @@ julia> mktemp() do file, io
             loadgraph(file, "something", MGFormat()) == example
         end
 true
-```
+```