Merge pull request #491 from JuliaRobotics/docs/20Q2/cleanupv08

Refactor docs structure for maintainability and v0.8

Author: Affie

docs/extra/CoreAPI.fods

@@ -1,5 +1,6 @@
 using Documenter
 using GraphPlot
+push!(ENV,"DFG_USE_CGDFG"=>"true")
 using DistributedFactorGraphs
 
 makedocs(
@@ -8,27 +9,24 @@ makedocs(
     sitename = "DistributedFactorGraphs.jl",
     pages = Any[
         "Home" => "index.md",
-        "Data Structure" => "DataStructure.md",
         "Getting Started" => [
-            "Introduction" => "getting_started.md",
+            "DFG Data Structures" => "DataStructure.md",
             "Building Graphs" => "BuildingGraphs.md",
-            "Using Graph Data" => "GraphData.md",
+            "Using Graph Elements" => "GraphData.md",
             "Drawing Graphs" => "DrawingGraphs.md",
-            "Traversing and Querying" => "TraversingAndQuerying.md",
-            "Common API Interface" => "ref_api.md"
+            "Quick API Reference" => "ref_api.md"
         ],
-        "DistributedFactorGraph API's" => [
-            "Graphs.jl" => "apis/graphs.md",
-            "LightGraphs.jl" => "apis/graphs.md",
-            "CloudGraphs.jl" => "apis/graphs.md",
-        ],
-        "Reference" => "func_ref.md"
+        # "DistributedFactorGraph API's" => [
+        #     "LightDFGs" => "apis/LightGraphs.md",
+        #     "CloudGraphsDFGs" => "apis/CloudGraphs.md",
+        # ],
+        "Function Reference" => "func_ref.md"
     ]
     # html_prettyurls = !("local" in ARGS),
     )
 
 deploydocs(
     repo   = "github.com/JuliaRobotics/DistributedFactorGraphs.jl.git",
     target = "build",
-    deps   = Deps.pip("mkdocs", "python-markdown-math")
+    # deps   = Deps.pip("mkdocs", "python-markdown-math")
 )

docs/make.jl

@@ -1,4 +1,4 @@
-# Creating Graphs
+# Building Graphs
 
 In this section constructing DFG graphs will be discussed. To start, bring DistributedFactorGraphs into your workspace:
 
@@ -18,22 +18,14 @@ using IncrementalInference
 
 ## Initializing a Graph
 
-DFG graphs can be built using various drivers (different representations of the underlying graph). At the moment DFG supports 3 drivers:
-- GraphsDFG: An in-memory graph that uses Graphs.jl for representing the graph.
+DFG graphs can be built using various drivers (different representations of the underlying graph). At the moment DFG supports 2 drivers:
 - LightDFG: An in-memory graph that uses LightGraphs.jl for representing the graph.
 - CloudGraphs: A database-driven graph that uses Neo4j.jl for interacting with the graph.
 
-In general the first two are used for building and solving graphs, and CloudGraphs is used for persisting in-memory graphs into a database. In the long term we recommend using the LightDFG driver for in-memory operation because Graphs.jl is not actively supported and over time that driver may be deprecated.
+In general the in-memory drivers are used for building and solving graphs, and CloudGraphs is used for persisting in-memory graphs into a database.
 
 To continue the example, run one of the following to create a DFG driver:
 
-### Creating a GraphsDFG Graph
-
-```julia
-# Create a DFG with default solver parameters using the Graphs.jl driver.
-dfg = GraphsDFG{SolverParams}(params=SolverParams())
-```
-
 ### Creating a LightDFG Graph
 
 ```julia
@@ -46,11 +38,7 @@ dfg = LightDFG{SolverParams}(params=SolverParams())
 ```julia
 # Create a DFG with no solver parameters (just to demonstrate the difference) using the CloudGraphs driver, and connect it to a local Neo4j instance.
 dfg = CloudGraphsDFG{NoSolverParams}("localhost", 7474, "neo4j", "test",
-                                "testUser", "testRobot", "testSession",
-                                nothing,
-                                nothing,
-                                IncrementalInference.decodePackedType,
-                                IncrementalInference.rebuildFactorMetadata!)
+                                     "testUser", "testRobot", "testSession")
 ```
 
 ## Creating Variables and Factors
@@ -64,7 +52,7 @@ Variables are added using IncrementalInference's `addVariable!` function. To cre
 - The variable's label (e.g. :x1 or :a)
 - The variable inference type (aka soft type), which is a subtype of InferenceVariable
 
-**NOTE**: Once variables are initialized to a specific soft type, variable node data (solver data) is templated to that type. 
+**NOTE**: Once variables are initialized to a specific soft type, variable node data (solver data) is templated to that type.
 
 In addition, the following optional parameters are provided:
 - Additional labels for the variable (in DFG these are referred to as tags)
@@ -114,40 +102,29 @@ Each variable and factor is uniquely identified by its label. The list of
 variable and factor labels can be retrieved with the `ls`/`listVariables` and
 `lsf`/`listFactors` functions:
 
-```@docs
-listVariables
-ls
-```
-
-```@docs
-listFactors
-lsf
-```
+- [`listVariables`](@ref)
+- [`ls`](@ref)
+- [`listFactors`](@ref)
+- [`lsf`](@ref)
 
 To list all variables or factors (instead of just their labels), use the
 `getVariables` and `getFactors` functions:
 
-```@docs
-getVariables
-getFactors
-```
+- [`getVariables`](@ref)
+- [`getFactors`](@ref)
+
+Traversing and Querying functions for finding the relationships and building subtraphs include:  
 
-**NOTE**: `getNeighbors` is also worth mentioning at this point as it is a simple way to
-find the bigraph relationships. More information on this and other ways to
-retrieve filtered lists of variables/factors (an area that's currently WIP in
-DFG) can be found in [Traversing and Querying](TraversingAndQuerying.md).  
+- [`getNeighbors`](@ref)
+- [`buildSubgraph`](@ref)
+- [`getBiadjacencyMatrix`](@ref)
 
 ## Getting (Reading) Variables and Factors
 
 Individual variables and factors can be retrieved from their labels using the following functions:
 
-```@docs
-getVariable
-```
-
-```@docs
-getFactor
-```
+- [`getVariable`](@ref)
+- [`getFactor`](@ref)
 
 It is worth noting that `getVariable` allows a user to retrieve only a single
 solver entry, so that subsets of the solver data can be retrieved individually
@@ -158,13 +135,9 @@ independently using the functions as discussed in the update section below.
 
 Full variables and factors can be updated using the following functions:
 
-```@docs
-updateVariable!
-```
+- [`updateVariable!`](@ref)
+- [`updateFactor!`](@ref)
 
-```@docs
-updateFactor!
-```
 
 **NOTE**: Skeleton and summary variables are read-only. To perform updates you
 should use the full factors and variables.
@@ -178,10 +151,5 @@ more detail in [Data Structure](DataStructure.md).
 
 Variables and factors can be deleted using the following functions:
 
-```@docs
-deleteVariable!
-```
-
-```@docs
-deleteFactor!
-```
+- [`deleteVariable!`](@ref)
+- [`deleteFactor!`](@ref)

docs/src/BuildingGraphs.md

@@ -1,12 +1,12 @@
-# Data Structure
+# DFG Data Structures
 
 Variables and factors can potentially contain a lot of data, so DFG has
 different structures that are specialized for each use-case and level of detail.
 For example, if you  want to retrieve just a simple summary of the structure,
 you can use the summary or skeleton structures to identify variables and factors
 of interest and then retrieve more detail on the subset.
 
-Note that drivers support all of the structures.
+Note that not all drivers support all of the structures.
 
 The following section discusses the datastructures for each level. A quick
 summary of the types and the available properties (some of which are derived) is provided below.
@@ -29,24 +29,18 @@ Accessible properties for each of the factor structures:
 
 ## DFG Skeleton
 
-```@docs
-SkeletonDFGVariable
-SkeletonDFGFactor
-```
+- [`SkeletonDFGVariable`](@ref)
+- [`SkeletonDFGFactor`](@ref)
 
 ## DFG Summary
 
-```@docs
-DFGVariableSummary
-DFGFactorSummary
-```
+- [`DFGVariableSummary`](@ref)
+- [`DFGFactorSummary`](@ref)
 
 ## Full DFG Node
 
-```@docs
-DFGVariable
-DFGFactor
-```
+- [`DFGVariable`](@ref)
+- [`DFGFactor`](@ref)
 
 ## Additional Offloaded Data
 

docs/src/DataStructure.md

@@ -8,7 +8,7 @@ Graphs can be visualized by using either `GraphPlot` or rendering to .dot files
 
 ```julia
 using Pkg
-Pkg.install("GraphPlot")
+Pkg.add("GraphPlot")
 ```
 
 Then bring `GraphPlot` in before DFG:
@@ -18,13 +18,13 @@ using GraphPlot
 using DistributedFactorGraphs
 ```
 
-Any factor graph can then be drawn by calling `dfgPlot`:
+Any factor graph can then be drawn by calling `dfgplot`:
 
 ```julia
 # Construct graph using IIF
 using IncrementalInference
 # Create graph
-dfg = GraphsDFG{SolverParams}(params=SolverParams())
+dfg = LightDFG{SolverParams}(params=SolverParams())
 v1 = addVariable!(dfg, :x0, ContinuousScalar, labels = [:POSE], solvable=1)
 v2 = addVariable!(dfg, :x1, ContinuousScalar, labels = [:POSE], solvable=1)
 v3 = addVariable!(dfg, :l0, ContinuousScalar, labels = [:LANDMARK], solvable=1)
@@ -39,9 +39,7 @@ dfgplot(dfg)
 
 ![imgs/initialgraph.jpg](imgs/initialgraph.jpg)
 
-```@docs
-dfgplot
-```
+- [`dfgplot`](@ref)
 
 ### Rendering GraphPlot to PDF
 
@@ -62,8 +60,8 @@ More information at [GraphPlot.jl](https://github.com/JuliaGraphs/GraphPlot.jl)
 Dot files are a standard format for visualizing graphs and applications such as
 xdot are available to view the files. Dot plotting does not require `GraphPlot`
 and can be drawn by either:
-- Calling `toDot` on any graph to produce a string of the graph
-- Calling `toDotFile` on any graph to save it directly to a dotfile
+- 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
 
 ```julia
 using DistributedFactorGraphs
@@ -83,8 +81,3 @@ toDotFile(dfg, "/tmp/test.dot")
 # Open with xdot
 run(`xdot /tmp/test.dot`)
 ```
-
-```@docs
-toDot
-toDotFile
-```