Fix documentation (#1104)

* Fix documentation * rm IIF dependency and examples from docs until DFG v1
JuliaRobotics · Nov 1, 2024 · 65fbc7c · 65fbc7c
1 parent fb7d8a8
commit 65fbc7c
Show file tree

Hide file tree

Showing 19 changed files with 522 additions and 548 deletions.
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -1,9 +1,9 @@
 [deps]
 Cairo = "159f3aea-2a34-519c-b102-8c37f9878175"
 Compose = "a81c6b42-2e10-5240-aca2-a61377ecd94b"
+DistributedFactorGraphs = "b5cc3c7e-6572-11e9-2517-99fb8daf2f04"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 GraphPlot = "a2cc645c-3eea-5389-862e-a155d0052231"
-IncrementalInference = "904591bb-b899-562f-9e6f-b8df64c7d480"
 
 [compat]
-Documenter = "0.27"
+Documenter = "1"
diff --git a/docs/extra/CoreAPI.fods b/docs/extra/CoreAPI.fods
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,6 +1,5 @@
 using Documenter
 using GraphPlot
-push!(ENV, "DFG_USE_CGDFG" => "true")
 using DistributedFactorGraphs
 
 makedocs(;
@@ -16,13 +15,14 @@ makedocs(;
             "Drawing Graphs" => "DrawingGraphs.md",
             "Quick API Reference" => "ref_api.md",
         ],
-        "Function Reference" => "func_ref.md",
+        "Reference" => ["func_ref.md", "services_ref.md", "blob_ref.md"],
     ],
+    # warnonly=[:doctest],
+    # checkdocs=:none,
     # html_prettyurls = !("local" in ARGS),
 )
 
 deploydocs(;
     repo = "github.com/JuliaRobotics/DistributedFactorGraphs.jl.git",
     target = "build",
-    # deps   = Deps.pip("mkdocs", "python-markdown-math")
 )
diff --git a/docs/src/BuildingGraphs.md b/docs/src/BuildingGraphs.md
@@ -2,7 +2,7 @@
 
 In this section constructing DFG graphs will be discussed. To start, bring DistributedFactorGraphs into your workspace:
 
-```@example buildingGraphs; continued = true
+```julia
 using DistributedFactorGraphs
 ```
 
@@ -14,7 +14,7 @@ So for the following examples, IncrementalInference will be used to create the v
 using Pkg
 Pkg.add("IncrementalInference")
 ```
-```@example buildingGraphs; continued = true
+```julia
 using IncrementalInference
 ```
 
@@ -30,7 +30,7 @@ To continue the example, run one of the following to create a DFG driver:
 
 ### Creating a GraphsDFG Graph
 
-```@example buildingGraphs; continued = true
+```julia
 # Create a DFG with default solver parameters using the Graphs.jl driver.
 dfg = GraphsDFG{SolverParams}(solverParams=SolverParams())
 ```
@@ -54,7 +54,7 @@ In addition, the following optional parameters are provided:
 
 Three variables are added:
 
-```@example buildingGraphs; continued = true
+```julia
 v1 = addVariable!(dfg, :x0, ContinuousScalar, tags = [:POSE], solvable=1)
 v2 = addVariable!(dfg, :x1, ContinuousScalar, tags = [:POSE], solvable=1)
 v3 = addVariable!(dfg, :l0, ContinuousScalar, tags = [:LANDMARK], solvable=1)
@@ -73,7 +73,7 @@ Additionally, the solvable flag is also set to indicate that the factor can be u
 
 Four factors are added: a prior, a linear conditional relationship with a normal distribution between x0 and x1, and a pair of linear conditional relationships between each pose and the landmark.
 
-```@example buildingGraphs; continued = true
+```julia
 prior = addFactor!(dfg, [:x0], Prior(Normal(0,1)))
 f1 = addFactor!(dfg, [:x0; :x1], LinearRelative(Normal(50.0,2.0)), solvable=1)
 f1 = addFactor!(dfg, [:l0; :x0], LinearRelative(Normal(40.0,5.0)), solvable=1)
@@ -97,12 +97,12 @@ variable and factor labels can be retrieved with the [`ls`](@ref)/[`listVariable
 [`lsf`](@ref)/[`listFactors`](@ref) functions:
 
 For example listing the variables in the graph we created above:
-```@example buildingGraphs
+```julia
 ls(dfg)
 ```
 
 Or listing the factors:
-```@example buildingGraphs
+```julia
 lsf(dfg)
 ```
 

diff --git a/docs/src/DataStructure.md b/docs/src/DataStructure.md
@@ -13,11 +13,11 @@ summary of the types and the available properties (some of which are derived) is
 
 Accessible properties for each of the variable structures:
 
-|                     | Label | Timestamp | Tags | Estimates | Soft Type | Solvable | Solver Data | Small Data | Big Data Entries |
-|---------------------|-------|-----------|------|-----------|-----------|----------|-------------|------------|------------------|
-| SkeletonDFGVariable | X     |           | X    |           |           |          |             |            |                  |
-| DFGVariableSummary  | X     | X         | X    | X         | Symbol    |          |             |            | X                |
-| DFGVariable         | X     | X         | X    | X         | X         | X        | X           | X          | X                |
+|                     | Label | Timestamp | Tags | Estimates | Soft Type | Solvable | Solver Data | Metadata | Blob Entries |
+|---------------------|-------|-----------|------|-----------|-----------|----------|-------------|----------|--------------|
+| SkeletonDFGVariable | X     |           | X    |           |           |          |             |          |              |
+| DFGVariableSummary  | X     | X         | X    | X         | Symbol    |          |             |          | X            |
+| DFGVariable         | X     | X         | X    | X         | X         | X        | X           | X        | X            |
 
 Accessible properties for each of the factor structures:
 
@@ -27,21 +27,26 @@ Accessible properties for each of the factor structures:
 | DFGFactorSummary  | X     | X         | X    |             |          |             |
 | DFGFactor         | X     | X         | X    | X           | X        | X           |
 
-## DFG Skeleton
+## DFG Skeleton types
 
 - [`SkeletonDFGVariable`](@ref)
 - [`SkeletonDFGFactor`](@ref)
 
-## DFG Summary
+## DFG Summary types
 
 - [`DFGVariableSummary`](@ref)
 - [`DFGFactorSummary`](@ref)
 
-## Full DFG Node
+## DFG Portable and Storeable types
+
+- [`Variable`](@ref)
+- [`PackedFactor`](@ref)
+
+## DFG Full solvable types
 
 - [`DFGVariable`](@ref)
 - [`DFGFactor`](@ref)
 
 ## Additional Offloaded Data
 
-Additional, larger data can be associated with variables using keyed big data entries.  
+Additional, larger data can be associated with variables and factors using keyed blob entries.  
diff --git a/docs/src/DrawingGraphs.md b/docs/src/DrawingGraphs.md
@@ -13,14 +13,14 @@ Pkg.add("GraphPlot")
 
 Then bring `GraphPlot` in before DFG:
 
-```@example plots; continued = true
+```julia
 using GraphPlot
 using DistributedFactorGraphs
 ```
 
 Any factor graph can then be drawn by calling [`plotDFG`](@ref):
 
-```@example plots
+```julia
 using Cairo # hide
 # Construct graph using IIF
 using IncrementalInference
@@ -42,7 +42,7 @@ plotDFG(dfg)
 
 The graph can be rendered to PDF, SVG or JPG in the following way by including compose:
 
-```@example plots
+```julia
 using Compose
 # lets add another variable and factor and plot it
 dfg.solverParams.graphinit = false # hide
@@ -52,7 +52,7 @@ addFactor!(dfg, [:x1; :x2], LinearRelative(Normal(50.0,2.0)));
 draw(SVG("graph.svg", 10cm, 10cm), plotDFG(dfg));
 nothing # hide
 ```
-![](graph.svg)
+FIXME show graph.svg
 
 
 ### More Information
@@ -67,7 +67,7 @@ and can be drawn by either:
 - Calling [`toDot`](@ref) on any graph to produce a string of the graph
 - Calling [`toDotFile`](@ref) on any graph to save it directly to a dotfile
 
-```@example
+```julia
 using DistributedFactorGraphs
 # Construct graph using IIF
 using IncrementalInference

diff --git a/docs/src/blob_ref.md b/docs/src/blob_ref.md
@@ -0,0 +1,34 @@
+# Blobs and BlobEntries
+
+```@contents
+Pages = [
+    "blob_ref.md"
+]
+Depth = 3
+```
+
+## Types
+```@autodocs
+Modules = [DistributedFactorGraphs]
+
+Pages = [
+    "DataBlobs/entities/BlobEntry.jl",
+    "DataBlobs/entities/BlobStores.jl",
+]
+
+```
+
+## Functions
+```@autodocs
+Modules = [DistributedFactorGraphs]
+
+Pages = [
+    "DataBlobs/services/BlobEntry.jl",
+    "DataBlobs/services/BlobStores.jl",
+    "DataBlobs/services/BlobPacking.jl",
+    "DataBlobs/services/HelpersDataWrapEntryBlob.jl",
+]
+
+```
+
+
diff --git a/docs/src/func_ref.md b/docs/src/func_ref.md
@@ -1,4 +1,4 @@
-# DistributedFactorGraphs Functions Reference
+# DistributedFactorGraphs Types
 
 ```@contents
 Pages = [
@@ -14,7 +14,7 @@ Modules = [DistributedFactorGraphs]
 Pages = ["DistributedFactorGraphs.jl"]
 ```
 
-## Entities
+## Types
 
 ### Abstract DFG
 
@@ -44,70 +44,11 @@ Modules = [DistributedFactorGraphs]
 Pages = ["entities/DFGFactor.jl"]
 ```
 
-## Services
-
-### Abstract DFG
-
-```@autodocs
-Modules = [DistributedFactorGraphs]
-Pages = ["services/AbstractDFG.jl"]
-```
-
-### Common Accessors
-
-Common Accessors to both variable and factor nodes
-
-```@autodocs
-Modules = [DistributedFactorGraphs]
-Pages = ["services/CommonAccessors.jl"]
-```
-
-### DFG Variable Accessors CRUD and SET opperations
-
-```@autodocs
-Modules = [DistributedFactorGraphs]
-Pages = ["services/DFGVariable.jl"]
-```
-
-### DFG Factor Accessors CRUD and SET opperations
-
-```@autodocs
-Modules = [DistributedFactorGraphs]
-Pages = ["services/DFGFactor.jl"]
-```
-
-### Printing
-
-```@autodocs
-Modules = [DistributedFactorGraphs]
-Pages = ["services/CustomPrinting.jl"]
-```
-
-### Compare Utilities
-
-```@autodocs
-Modules = [DistributedFactorGraphs]
-Pages = ["services/CompareUtils.jl"]
-```
-
-### Common Functions
-
-```@autodocs
-Modules = [DistributedFactorGraphs]
-Pages = ["src/Common.jl"]
-```
-
-### Serialization
-
-```@autodocs
-Modules = [DistributedFactorGraphs]
-Pages = ["services/Serialization.jl"]
-```
-
 ## DFG Plots [GraphPlot.jl]
 
 ```@autodocs
-Modules = [DFGPlots]
+Modules = [DistributedFactorGraphs]
+Pages = ["weakdeps_prototypes.jl"]
 ```
 
 ## Drivers
@@ -123,18 +64,4 @@ Modules = [GraphsDFGs]
 ```@autodocs
 Modules = [DistributedFactorGraphs]
 Pages = ["FileDFG.jl"]
-```
-
-## Data Entries and Blobs
-
-```@autodocs
-Modules = [DistributedFactorGraphs]
-
-Pages = ["entities/AbstractDataEntries.jl",
-        "services/AbstractDataEntries.jl",
-        "services/BlobStores.jl",
-        "services/DataEntryBlob.jl",
-        "services/FileDataEntryBlob.jl",
-        "services/InMemoryDataEntryBlob.jl"]
-
-```
+```
diff --git a/docs/src/imgs/CoreAPI.png b/docs/src/imgs/CoreAPI.png
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -24,5 +24,7 @@ Pages = [
     "DrawingGraphs.md"
     "ref_api.md"
     "func_ref.md"
+    "services_ref.md"
+    "blob_ref.md"
 ]
 ```