docs improvements (JuliaGraphs#539)

Author: CarloLucibello

.github/workflows/multidocs.yml

@@ -61,16 +61,6 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
           DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
 
-      # Build tutorials
-      - name: Install dependencies for tutorials
-        run: julia --project=tutorials/docs/ -e '
-          using Pkg;
-          pkg"dev ./GraphNeuralNetworks ./GNNlib ./GNNGraphs";
-          Pkg.instantiate();
-          include("tutorials/docs/make.jl")'
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
-          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
 
       # Build and deploy multidocs
       - name: Install dependencies for multidocs

GNNGraphs/docs/make.jl

@@ -1,6 +1,7 @@
 using Documenter
 using DocumenterInterLinks
 using GNNGraphs
+using MLUtils # this is needed by setdocmeta!
 import Graphs
 using Graphs: induced_subgraph
 

GNNGraphs/docs/src/api/gnngraph.md

@@ -1,5 +1,6 @@
 ```@meta
 CurrentModule = GNNGraphs
+CollapsedDocStrings = true
 ```
 
 # GNNGraph
@@ -10,12 +11,6 @@ Besides the methods documented here, one can rely on the large set of functional
 given by [Graphs.jl](https://github.com/JuliaGraphs/Graphs.jl) thanks to the fact
 that `GNNGraph` inherits from `Graphs.AbstractGraph`.
 
-## Index 
-
-```@index
-Order = [:type, :function]
-Pages   = ["gnngraph.md"]
-```
 
 ## GNNGraph type
 
@@ -36,7 +31,7 @@ Private = false
 
 ```@autodocs
 Modules = [GNNGraphs]
-Pages   = ["query.jl"]
+Pages   = ["src/query.jl"]
 Private = false
 ```
 
@@ -48,7 +43,7 @@ Graphs.neighbors(::GNNGraph, ::Integer)
 
 ```@autodocs
 Modules = [GNNGraphs]
-Pages   = ["transform.jl"]
+Pages   = ["src/transform.jl"]
 Private = false
 ```
 
@@ -63,17 +58,16 @@ GNNGraphs.color_refinement
 
 ```@autodocs
 Modules = [GNNGraphs]
-Pages   = ["generate.jl"]
+Pages   = ["src/generate.jl"]
 Private = false
 Filter = t -> typeof(t) <: Function && t!=rand_temporal_radius_graph && t!=rand_temporal_hyperbolic_graph
-
 ```
 
 ## Operators
 
 ```@autodocs
 Modules = [GNNGraphs]
-Pages   = ["operators.jl"]
+Pages   = ["src/operators.jl"]
 Private = false
 ```
 
@@ -85,7 +79,7 @@ Base.intersect
 
 ```@autodocs
 Modules = [GNNGraphs]
-Pages   = ["sampling.jl"]
+Pages   = ["src/sampling.jl"]
 Private = false
 ```
 

GNNGraphs/docs/src/api/heterograph.md

@@ -1,17 +1,40 @@
+```@meta
+CurrentModule = GNNGraphs
+CollapsedDocStrings = true
+```
+
 # Heterogeneous Graphs
 
 
 ## GNNHeteroGraph
 Documentation page for the type `GNNHeteroGraph` representing heterogeneous graphs, where  nodes and edges can have different types.
 
-
 ```@autodocs
 Modules = [GNNGraphs]
 Pages   = ["gnnheterograph.jl"]
 Private = false
 ```
 
-```@docs
-Graphs.has_edge(::GNNHeteroGraph, ::Tuple{Symbol, Symbol, Symbol}, ::Integer, ::Integer)
+## Query
+
+```@autodocs
+Modules = [GNNGraphs]
+Pages   = ["gnnheterograph/query.jl"]
+Private = false
+```
+
+## Transform
+
+```@autodocs
+Modules = [GNNGraphs]
+Pages   = ["gnnheterograph/transform.jl"]
+Private = false
 ```
 
+## Generate
+
+```@autodocs
+Modules = [GNNGraphs]
+Pages   = ["gnnheterograph/generate.jl"]
+Private = false
+```

GNNGraphs/docs/src/api/samplers.md

@@ -1,12 +1,10 @@
 ```@meta
 CurrentModule = GNNGraphs
+CollapsedDocStrings = true
 ```
 
 # Samplers
 
-
-## Docs
-
 ```@autodocs
 Modules = [GNNGraphs]
 Pages   = ["samplers.jl"]

GNNGraphs/docs/src/api/temporalgraph.md

@@ -1,3 +1,8 @@
+```@meta
+CurrentModule = GNNGraphs
+CollapsedDocStrings = true
+```
+
 # Temporal Graphs
 
 ## TemporalSnapshotsGNNGraph
@@ -10,7 +15,7 @@ Pages   = ["temporalsnapshotsgnngraph.jl"]
 Private = false
 ```
 
-## TemporalSnapshotsGNNGraph random generators
+## Random Generators
 
 ```@docs
 rand_temporal_radius_graph

GNNGraphs/docs/src/guides/heterograph.md

@@ -1,3 +1,7 @@
+```@meta
+CurrentModule = GNNGraphs
+```
+
 # Heterogeneous Graphs
 
 Heterogeneous graphs (also called heterographs), are graphs where each node has a type,
@@ -67,18 +71,15 @@ julia> g.num_edges
 Dict{Tuple{Symbol, Symbol, Symbol}, Int64} with 1 entry:
   (:user, :rate, :movie) => 4
 
-# source and target node for a given relation
-julia> edge_index(g, (:user, :rate, :movie))
+julia> edge_index(g, (:user, :rate, :movie)) # source and target node for a given relation
 ([1, 1, 2, 3], [7, 13, 5, 7])
 
-# node types
-julia> g.ntypes
+julia> g.ntypes  # node types
 2-element Vector{Symbol}:
  :user
  :movie
 
-# edge types
-julia> g.etypes
+julia> g.etypes  # edge types
 1-element Vector{Tuple{Symbol, Symbol, Symbol}}:
  (:user, :rate, :movie)
 ```
@@ -120,8 +121,8 @@ GNNHeteroGraph:
 Batching is automatically performed by the [`DataLoader`](https://fluxml.ai/Flux.jl/stable/data/mlutils/#MLUtils.DataLoader) iterator
 when the `collate` option is set to `true`.
 
-```jldoctest hetero
-using Flux: DataLoader
+```julia
+using MLUtils: DataLoader
 
 data = [rand_bipartite_heterograph((5, 10), 20, 
             ndata=Dict(:A=>rand(Float32, 3, 5))) 

GNNGraphs/docs/src/guides/temporalgraph.md

@@ -1,3 +1,7 @@
+```@meta
+CurrentModule = GNNGraphs
+```
+
 # Temporal Graphs
 
 Temporal Graphs are graphs with time varying topologies and  features. In GNNGraphs.jl, temporal graphs with fixed number of nodes over time are supported by the [`TemporalSnapshotsGNNGraph`](@ref) type.
@@ -45,7 +49,7 @@ TemporalSnapshotsGNNGraph:
 
 See [`rand_temporal_radius_graph`](@ref) and [`rand_temporal_hyperbolic_graph`](@ref) for generating random temporal graphs. 
 
-```jldoctest temporal
+```julia
 julia> tg = rand_temporal_radius_graph(10, 3, 0.1, 0.5)
 TemporalSnapshotsGNNGraph:
   num_nodes: [10, 10, 10]
@@ -97,28 +101,30 @@ A temporal graph can store global feature for the entire time series in the `tgd
 Also, each snapshot can store node, edge, and graph features in the `ndata`, `edata`, and `gdata` fields, respectively. 
 
 ```jldoctest temporal
-julia> snapshots = [rand_graph(10,20; ndata = rand(3,10)), rand_graph(10,14; ndata = rand(4,10)), rand_graph(10,22; ndata = rand(5,10))]; # node features at construction time
+julia> snapshots = [rand_graph(10, 20; ndata = rand(Float32, 3, 10)), 
+                    rand_graph(10, 14; ndata = rand(Float32, 4, 10)), 
+                    rand_graph(10, 22; ndata = rand(Float32, 5, 10))]; # node features at construction time
 
 julia> tg = TemporalSnapshotsGNNGraph(snapshots);
 
-julia> tg.tgdata.y = rand(3,1); # add global features after construction
+julia> tg.tgdata.y = rand(Float32, 3, 1); # add global features after construction
 
 julia> tg
 TemporalSnapshotsGNNGraph:
   num_nodes: [10, 10, 10]
   num_edges: [20, 14, 22]
   num_snapshots: 3
   tgdata:
-        y = 3×1 Matrix{Float64}
+        y = 3×1 Matrix{Float32}
 
 julia> tg.ndata # vector of DataStore containing node features for each snapshot
 3-element Vector{DataStore}:
  DataStore(10) with 1 element:
-  x = 3×10 Matrix{Float64}
+  x = 3×10 Matrix{Float32}
  DataStore(10) with 1 element:
-  x = 4×10 Matrix{Float64}
+  x = 4×10 Matrix{Float32}
  DataStore(10) with 1 element:
-  x = 5×10 Matrix{Float64}
+  x = 5×10 Matrix{Float32}
 
 julia> [ds.x for ds in tg.ndata]; # vector containing the x feature of each snapshot
 

GNNGraphs/src/GNNGraphs.jl

@@ -4,7 +4,7 @@ using SparseArrays
 using Functors: @functor
 import Graphs
 using Graphs: AbstractGraph, outneighbors, inneighbors, adjacency_matrix, degree, 
-              has_self_loops, is_directed, induced_subgraph
+              has_self_loops, is_directed, induced_subgraph, has_edge
 import NearestNeighbors
 import NNlib
 import StatsBase
@@ -30,7 +30,7 @@ export GNNGraph,
        edge_features,
        graph_features
 
-include("gnnheterograph.jl")
+include("gnnheterograph/gnnheterograph.jl")
 export GNNHeteroGraph,
        num_edge_types,
        num_node_types,
@@ -44,6 +44,7 @@ export TemporalSnapshotsGNNGraph,
        # remove_snapshot!
 
 include("query.jl")
+include("gnnheterograph/query.jl")
 export adjacency_list,
        edge_index,
        get_edge_weight,
@@ -58,13 +59,15 @@ export adjacency_list,
 # from Graphs
        adjacency_matrix,
        degree,
-       has_self_loops,
+       has_edge, 
        has_isolated_nodes,
+       has_self_loops,
        inneighbors,
        outneighbors,
        khop_adj
 
 include("transform.jl")
+include("gnnheterograph/transform.jl")
 export add_nodes,
        add_edges,
        add_self_loops,
@@ -88,6 +91,7 @@ export add_nodes,
        blockdiag
 
 include("generate.jl")
+include("gnnheterograph/generate.jl")
 export rand_graph,
        rand_heterograph,
        rand_bipartite_heterograph,
@@ -104,6 +108,7 @@ include("operators.jl")
 
 include("convert.jl")
 include("utils.jl")
+include("gnnheterograph/utils.jl")
 export sort_edge_index, color_refinement
 
 include("gatherscatter.jl")

GNNGraphs/src/datastore.jl

@@ -15,29 +15,12 @@ DataStore(3) with 2 elements:
   x = 2×3 Matrix{Float32}
 
 julia> ds = DataStore(3, Dict(:x => rand(Float32, 2, 3), :y => rand(Float32, 3))); # equivalent to above
-
-julia> ds = DataStore(3, (x = rand(Float32, 2, 3), y = rand(Float32, 30)))
-ERROR: AssertionError: DataStore: data[y] has 30 observations, but n = 3
-Stacktrace:
- [1] DataStore(n::Int64, data::Dict{Symbol, Any})
-   @ GNNGraphs ~/.julia/dev/GNNGraphs/datastore.jl:54
- [2] DataStore(n::Int64, data::NamedTuple{(:x, :y), Tuple{Matrix{Float32}, Vector{Float32}}})
-   @ GNNGraphs ~/.julia/dev/GNNGraphs/datastore.jl:73
- [3] top-level scope
-   @ REPL[13]:1
-
-julia> ds = DataStore(x = randFloat32, 2, 3), y = rand(Float32, 30)) # no checks
-DataStore() with 2 elements:
-  y = 30-element Vector{Float32}
-  x = 2×3 Matrix{Float32}
-  y = 30-element Vector{Float64}
-  x = 2×3 Matrix{Float64}
 ```
 
 The `DataStore` has an interface similar to both dictionaries and named tuples.
 Arrays can be accessed and added using either the indexing or the property syntax:
 
-```jldoctest datastore
+```jldoctest docstr_datastore
 julia> ds = DataStore(x = ones(Float32, 2, 3), y = zeros(Float32, 3))
 DataStore() with 2 elements:
   y = 3-element Vector{Float32}
@@ -59,14 +42,16 @@ The `DataStore` can be iterated over, and the keys and values can be accessed
 using `keys(ds)` and `values(ds)`. `map(f, ds)` applies the function `f`
 to each feature array:
 
-```jldoctest datastore
+```jldoctest docstr_datastore
 julia> ds2 = map(x -> x .+ 1, ds)
-DataStore() with 2 elements:
-  a = 2-element Vector{Float64}
-  b = 2-element Vector{Float64}
+DataStore() with 3 elements:
+  y = 3-element Vector{Float32}
+  z = 3-element Vector{Float32}
+  x = 2×3 Matrix{Float32}
 
-julia> ds2.a
-2-element Vector{Float64}:
+julia> ds2.z
+3-element Vector{Float32}:
+ 1.0
  1.0
  1.0
 ```