include all docs (#535)

JuliaGraphs · Dec 2, 2024 · 5b5663e · 5b5663e
1 parent ca90e88
commit 5b5663e
Show file tree

Hide file tree

Showing 19 changed files with 175 additions and 162 deletions.
diff --git a/.github/workflows/multidocs.yml b/.github/workflows/multidocs.yml
@@ -20,81 +20,63 @@ jobs:
       - name: Set up
         run: git config --global init.defaultBranch master
 
-      # Build GNNGraphs docs
-      - name: Install dependencies for GNNGraphs
+      - name: Build GNNGraphs docs
         run: 
           julia --project=GNNGraphs/docs/ -e '
           using Pkg;
-          Pkg.develop(PackageSpec(path=joinpath(pwd(), "GNNGraphs")));
-          Pkg.instantiate();'
-      - name: Build GNNGraphs docs
+          pkg"dev ./GNNGraphs";
+          Pkg.instantiate();
+          include("GNNGraphs/docs/make.jl")'
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
           DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
-        run: julia --project=GNNGraphs/docs/ GNNGraphs/docs/make.jl
 
-      # Build GNNlib docs
-      - name: Install dependencies for GNNlib
-        run: julia --project=GNNlib/docs/ -e 'using Pkg; Pkg.instantiate();'
       - name: Build GNNlib docs
+        run: julia --project=GNNlib/docs/ -e '
+          using Pkg;
+          pkg"dev ./GNNlib ./GNNGraphs";
+          Pkg.instantiate();
+          include("GNNlib/docs/make.jl")'
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
           DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
-        run: julia --project=GNNlib/docs/ GNNlib/docs/make.jl
 
-      # Build GNNLux docs
-      - name: Install dependencies for GNNLux
+      - name: Build GNNLux docs
         run: julia --project=GNNLux/docs/ -e '
             using Pkg;
-            Pkg.develop(PackageSpec(path=joinpath(pwd(), "GNNLux"))); 
-            Pkg.instantiate();'
-      - name: Build GNNLux docs
+            pkg"dev ./GNNLux ./GNNlib ./GNNGraphs";
+            Pkg.instantiate();
+            include("GNNLux/docs/make.jl")'
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
           DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
-        run: julia --project=GNNLux/docs/ GNNLux/docs/make.jl
 
-      # Build GraphNeuralNetworks docs
-      - name: Install dependencies for GraphNeuralNetworks
-        run: julia --project=GraphNeuralNetworks/docs/ -e '
-            using Pkg;
-            Pkg.develop(PackageSpec(path=joinpath(pwd(), "GraphNeuralNetworks"))); 
-            Pkg.instantiate();'
       - name: Build GraphNeuralNetworks docs
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
-          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
-        run: julia --project=GraphNeuralNetworks/docs/ GraphNeuralNetworks/docs/make.jl
-
-      # Build  multidocs
-      - name: Install dependencies for main docs
-        run: julia --project=GraphNeuralNetworks/docs/ -e ' 
+        run: julia --project=GraphNeuralNetworks/docs/ -e '
             using Pkg;
-            Pkg.develop(PackageSpec(path=joinpath(pwd(), "GraphNeuralNetworks"))); 
-            Pkg.instantiate();'
-      - name: Build main docs
+            pkg"dev ./GraphNeuralNetworks ./GNNlib ./GNNGraphs";
+            Pkg.instantiate();
+            include("GraphNeuralNetworks/docs/make.jl")'
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
           DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
-        run: julia --project=GraphNeuralNetworks/docs/make.jl
 
       # Build tutorials
       - name: Install dependencies for tutorials
-        run: julia --project=tutorials/docs/ -e 'using Pkg; Pkg.instantiate();'
-      - name: Build 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 }}
-        run: julia --project=tutorials/docs/ tutorials/docs/make.jl
-
+
       # Build and deploy multidocs
       - name: Install dependencies for multidocs
         run: julia --project=docs/ -e '
           using Pkg;
-          Pkg.develop([PackageSpec(path=joinpath(pwd(), "GraphNeuralNetworks")),
-                      PackageSpec(path=joinpath(pwd(), "GNNGraphs")),
-                      PackageSpec(path=joinpath(pwd(), "GNNlib")),
-                      PackageSpec(path=joinpath(pwd(), "GNNLux"))]);
+          pkg"dev ./GraphNeuralNetworks ./GNNlib ./GNNGraphs ./GNNLux";
           Pkg.instantiate();'
       - name: Check if objects.inv exists for GraphNeuralNetworks
         run: |

diff --git a/.gitignore b/.gitignore
@@ -15,5 +15,6 @@ GNNGraphs/docs/build
 GNNlib/docs/build
 GNNLux/docs/build
 GraphNeuralNetworks/docs/build
-GraphNeuralNetworks/docs/src/other
+GraphNeuralNetworks/docs/src/GNNGraphs
+GraphNeuralNetworks/docs/src/GNNlib
 tutorials/docs/build
diff --git a/GNNGraphs/docs/Project.toml b/GNNGraphs/docs/Project.toml
@@ -4,3 +4,6 @@ DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
 GNNGraphs = "aed8fd31-079b-4b5a-b342-a13352159b8c"
 Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
 LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589"
+MLDatasets = "eb30cadb-4394-5ae3-aed4-317e484a6458"
+MLUtils = "f1d291b0-491e-4a28-83b9-f70985020b54"
+SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
diff --git a/GNNGraphs/docs/make.jl b/GNNGraphs/docs/make.jl
@@ -4,29 +4,48 @@ using GNNGraphs
 import Graphs
 using Graphs: induced_subgraph
 
-assets=[]
-prettyurls = get(ENV, "CI", nothing) == "true"
-mathengine = MathJax3()
 
+DocMeta.setdocmeta!(GNNGraphs, :DocTestSetup, :(using GNNGraphs, MLUtils); recursive = true)
+
+mathengine = MathJax3(Dict(:loader => Dict("load" => ["[tex]/require", "[tex]/mathtools"]),
+    :tex => Dict("inlineMath" => [["\$", "\$"], ["\\(", "\\)"]],
+        "packages" => [
+            "base",
+            "ams",
+            "autoload",
+            "mathtools",
+            "require"
+        ])))
 
 makedocs(;
-         modules = [GNNGraphs],
-         doctest = false,
-         clean = true,
-         format = Documenter.HTML(; mathengine, prettyurls, assets = assets, size_threshold=nothing),
-         sitename = "GNNGraphs.jl",
-         pages = ["Home" => "index.md",
-            "Guides" => [
-               "Graphs" => ["guides/gnngraph.md", "guides/heterograph.md", "guides/temporalgraph.md"],
-               "Datasets" => "guides/datasets.md",
-            ],
-            "API Reference" => [
-                 "GNNGraph" => "api/gnngraph.md",
-                 "GNNHeteroGraph" => "api/heterograph.md",
-                 "TemporalSnapshotsGNNGraph" => "api/temporalgraph.md",
-                 "Samplers" => "api/samplers.md",
-              ],      
-         ]
-         )
+    modules = [GNNGraphs],
+    doctest = false, # TODO enable doctest
+    format = Documenter.HTML(; mathengine, 
+                    prettyurls = get(ENV, "CI", nothing) == "true", 
+                    assets = [],
+                    size_threshold=nothing, 
+                    size_threshold_warn=200000),sitename = "GNNGraphs.jl",
+    pages = [
+    "Home" => "index.md",
+
+    "Guides" => [
+        "Graphs" => [
+            "guides/gnngraph.md", 
+            "guides/heterograph.md", 
+            "guides/temporalgraph.md"
+        ],
+        "Datasets" => "guides/datasets.md",
+    ],
+
+    "API Reference" => [
+        "GNNGraph" => "api/gnngraph.md",
+        "GNNHeteroGraph" => "api/heterograph.md",
+        "TemporalSnapshotsGNNGraph" => "api/temporalgraph.md",
+        "Samplers" => "api/samplers.md",
+        ],      
+    ]
+)
 
-deploydocs(;repo = "github.com/JuliaGraphs/GraphNeuralNetworks.jl.git", devbranch = "master", dirname = "GNNGraphs")
+deploydocs(repo = "github.com/JuliaGraphs/GraphNeuralNetworks.jl.git", 
+         devbranch = "master", 
+         dirname = "GNNGraphs")
diff --git a/GNNGraphs/docs/src/guides/gnngraph.md b/GNNGraphs/docs/src/guides/gnngraph.md
@@ -155,11 +155,10 @@ that contains the total number of the original nodes
 and where the original graphs are disjoint subgraphs.
 
 ```julia
-using Flux
-using Flux: DataLoader
+using MLUtils
 
 data = [rand_graph(10, 30, ndata=rand(Float32, 3, 10)) for _ in 1:160]
-gall = Flux.batch(data)
+gall = MLUtils.batch(data)
 
 # gall is a GNNGraph containing many graphs
 @assert gall.num_graphs == 160 
@@ -172,7 +171,7 @@ g23 = getgraph(gall, 2:3)
 @assert g23.num_nodes == 20   # 10 nodes x 2 graphs
 @assert g23.num_edges == 60  # 30 undirected edges X 2 graphs
 
-# We can pass a GNNGraph to Flux's DataLoader
+# We can pass a GNNGraph to MLUtils' DataLoader
 train_loader = DataLoader(gall, batchsize=16, shuffle=true)
 
 for g in train_loader
@@ -193,7 +192,7 @@ an option for mini-batch iteration, the recommended way for better performance i
 to pass an array of graphs directly and set the `collate` option to `true`:
 
 ```julia
-using Flux: DataLoader
+using MLUtils: DataLoader
 
 data = [rand_graph(10, 30, ndata=rand(Float32, 3, 10)) for _ in 1:320]
 
@@ -220,7 +219,7 @@ g′ = add_edges(g, [1, 2], [2, 3]) # add edges 1->2 and 2->3
 Move a `GNNGraph` to a CUDA device using `Flux.gpu` method. 
 
 ```julia
-using CUDA, Flux
+using Flux, CUDA # or using Metal or using AMDGPU 
 
 g_gpu = g |> Flux.gpu
 ```

diff --git a/GNNGraphs/docs/src/guides/heterograph.md b/GNNGraphs/docs/src/guides/heterograph.md
@@ -13,7 +13,9 @@ the type [`GNNHeteroGraph`](@ref).
 ## Creating a Heterograph
 
 A heterograph can be created empty or by passing pairs `edge_type => data` to the constructor.
-```jldoctest
+```jldoctest hetero
+julia> using GNNGraphs
+
 julia> g = GNNHeteroGraph()
 GNNHeteroGraph:
   num_nodes: Dict()
@@ -31,7 +33,7 @@ GNNHeteroGraph:
   num_edges: Dict((:user, :rate, :movie) => 4)
 ```
 New relations, possibly with new node types, can be added with the function [`add_edges`](@ref).
-```jldoctest
+```jldoctest hetero
 julia> g = add_edges(g, (:user, :like, :actor) => ([1,2,3,3,3], [3,5,1,9,4]))
 GNNHeteroGraph:
   num_nodes: Dict(:actor => 9, :movie => 13, :user => 3)
@@ -40,7 +42,7 @@ GNNHeteroGraph:
 See [`rand_heterograph`](@ref), [`rand_bipartite_heterograph`](@ref)
 for generating random heterographs. 
 
-```jldoctest
+```jldoctest hetero
 julia> g = rand_bipartite_heterograph((10, 15), 20)
 GNNHeteroGraph:
   num_nodes: Dict(:A => 10, :B => 15)
@@ -50,7 +52,7 @@ GNNHeteroGraph:
 ## Basic Queries
 
 Basic queries are similar to those for homogeneous graphs:
-```jldoctest
+```jldoctest hetero
 julia> g = GNNHeteroGraph((:user, :rate, :movie) => ([1,1,2,3], [7,13,5,7]))
 GNNHeteroGraph:
   num_nodes: Dict(:movie => 13, :user => 3)
@@ -84,7 +86,7 @@ julia> g.etypes
 ## Data Features
 
 Node, edge, and graph features can be added at construction time or later using:
-```jldoctest
+```jldoctest hetero
 # equivalent to g.ndata[:user][:x] = ...
 julia> g[:user].x = rand(Float32, 64, 3);
 
@@ -106,10 +108,10 @@ GNNHeteroGraph:
 
 ## Batching
 Similarly to graphs, also heterographs can be batched together.
-```jldoctest
+```jldoctest hetero
 julia> gs = [rand_bipartite_heterograph((5, 10), 20) for _ in 1:32];
 
-julia> Flux.batch(gs)
+julia> MLUtils.batch(gs)
 GNNHeteroGraph:
   num_nodes: Dict(:A => 160, :B => 320)
   num_edges: Dict((:A, :to, :B) => 640, (:B, :to, :A) => 640)
@@ -118,7 +120,7 @@ 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
+```jldoctest hetero
 using Flux: DataLoader
 
 data = [rand_bipartite_heterograph((5, 10), 20, 

diff --git a/GNNGraphs/docs/src/guides/temporalgraph.md b/GNNGraphs/docs/src/guides/temporalgraph.md
@@ -6,7 +6,9 @@ Temporal Graphs are graphs with time varying topologies and  features. In GNNGra
 
 A temporal graph can be created by passing a list of snapshots to the constructor. Each snapshot is a [`GNNGraph`](@ref). 
 
-```jldoctest
+```jldoctest temporal
+julia> using GNNGraphs
+
 julia> snapshots = [rand_graph(10,20) for i in 1:5];
 
 julia> tg = TemporalSnapshotsGNNGraph(snapshots)
@@ -18,14 +20,14 @@ TemporalSnapshotsGNNGraph:
 
 A new temporal graph can be created by adding or removing snapshots to an existing temporal graph. 
 
-```jldoctest
+```jldoctest temporal
 julia> new_tg = add_snapshot(tg, 3, rand_graph(10, 16)) # add a new snapshot at time 3
 TemporalSnapshotsGNNGraph:
   num_nodes: [10, 10, 10, 10, 10, 10]
   num_edges: [20, 20, 16, 20, 20, 20]
   num_snapshots: 6
 ```
-```jldoctest
+```jldoctest temporal
 julia> snapshots = [rand_graph(10,20), rand_graph(10,14), rand_graph(10,22)];
 
 julia> tg = TemporalSnapshotsGNNGraph(snapshots)
@@ -43,7 +45,7 @@ TemporalSnapshotsGNNGraph:
 
 See [`rand_temporal_radius_graph`](@ref) and [`rand_temporal_hyperbolic_graph`](@ref) for generating random temporal graphs. 
 
-```jldoctest
+```jldoctest temporal
 julia> tg = rand_temporal_radius_graph(10, 3, 0.1, 0.5)
 TemporalSnapshotsGNNGraph:
   num_nodes: [10, 10, 10]
@@ -54,7 +56,7 @@ TemporalSnapshotsGNNGraph:
 ## Basic Queries
 
 Basic queries are similar to those for [`GNNGraph`](@ref)s:
-```jldoctest
+```jldoctest temporal
 julia> snapshots = [rand_graph(10,20), rand_graph(10,14), rand_graph(10,22)];
 
 julia> tg = TemporalSnapshotsGNNGraph(snapshots)
@@ -94,7 +96,7 @@ GNNGraph:
 A temporal graph can store global feature for the entire time series in the `tgdata` filed.
 Also, each snapshot can store node, edge, and graph features in the `ndata`, `edata`, and `gdata` fields, respectively. 
 
-```jldoctest
+```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> tg = TemporalSnapshotsGNNGraph(snapshots);
@@ -124,22 +126,4 @@ julia> [g.x for g in tg.snapshots]; # same vector as above, now accessing
                                    # the x feature directly from the snapshots
 ```
 
-## Graph convolutions on TemporalSnapshotsGNNGraph
-
-A graph convolutional layer can be applied to each snapshot independently, in the next example we apply a `GINConv` layer to each snapshot of a `TemporalSnapshotsGNNGraph`.  
-
-```jldoctest
-julia> using GNNGraphs, Flux
-
-julia> snapshots = [rand_graph(10, 20; ndata = rand(3, 10)), rand_graph(10, 14; ndata = rand(3, 10))];
-
-julia> tg = TemporalSnapshotsGNNGraph(snapshots);
-
-julia> m = GINConv(Dense(3 => 1), 0.4);
-
-julia> output = m(tg, tg.ndata.x);
-
-julia> size(output[1])
-(1, 10)
-```