Fixes #75

Author: VEZY

docs/make.jl

@@ -23,14 +23,14 @@ makedocs(;
             "Our implementation" => "the_mtg/our_implementation.md"
         ],
         "Tutorials" => [
-            "tutorials/0.read_write.md",
-            "tutorials/1.manipulate_node.md",
-            "tutorials/2.descendants_ancestors_filters.md",
-            "tutorials/3.transform_mtg.md",
-            "tutorials/4.convert_mtg.md",
-            "tutorials/5.plotting.md",
-            "tutorials/6.add_remove_nodes.md",
-            "tutorials/7.performance_considerations.md",
+            "Read and Write MTGs" => "tutorials/0.read_write.md",
+            "Create and Manipulate Nodes" => "tutorials/1.manipulate_node.md",
+            "Traversal, Descendants, Ancestors and Filters" => "tutorials/2.descendants_ancestors_filters.md",
+            "Transform and Select Attributes" => "tutorials/3.transform_mtg.md",
+            "Convert MTGs to Tables and Graphs" => "tutorials/4.convert_mtg.md",
+            "Plot MTGs" => "tutorials/5.plotting.md",
+            "Add and Remove Nodes" => "tutorials/6.add_remove_nodes.md",
+            "Performance Considerations" => "tutorials/7.performance_considerations.md",
         ],
         "API" => "api.md",
     ]

docs/src/get_started.md

@@ -4,6 +4,8 @@
 
 This page let's you take a peek at what the package is capable of. If you want a better, more in-depth introduction to the package, take a look at the tutorials, starting from [Read and Write MTGs](@ref). If you don't know what an MTG is, you can read more about starting from [The MTG concept](@ref).
 
+If your main goal is to query trees (children, descendants, ancestors, filters), go directly to [Traversal, descendants, ancestors and filters](@ref).
+
 ## Installation
 
 You must have a working Julia installation on your computer. The version of Julia should be greater than 1.3.
@@ -80,3 +82,11 @@ You can also convert your MTG to a [MetaGraph](https://juliagraphs.org/MetaGraph
 ```@example usepkg
 MetaGraph(mtg)
 ```
+
+## Next step: traversal tutorial
+
+If you are new to MTGs or graph vocabulary, this is usually the best next page:
+
+- [Traversal, descendants, ancestors and filters](@ref)
+
+It explains these words in plain language and gives practical query recipes.

docs/src/index.md

@@ -25,6 +25,8 @@ The MTG format helps describe the plant at different scales at the same time. Fo
 
 You can find out how to use the package on the [Getting started](@ref) section, or more about the MTG format in the [The MTG concept](@ref).
 
+If your immediate goal is querying MTGs (descendants, ancestors, filters), go to [Traversal, descendants, ancestors and filters](@ref).
+
 ## References
 
 Godin, C., et Y. Caraglio. 1998. « A Multiscale Model of Plant Topological Structures ». Journal of Theoretical Biology 191 (1): 1‑46. https://doi.org/10.1006/jtbi.1997.0561.

docs/src/tutorials/2.descendants_ancestors_filters.md

@@ -1,4 +1,4 @@
-# Node attributes
+# Traversal, descendants, ancestors and filters
 
 ```@setup usepkg
 using MultiScaleTreeGraph
@@ -17,6 +17,47 @@ file = joinpath(dirname(dirname(pathof(MultiScaleTreeGraph))),"test","files","si
 mtg = read_mtg(file)
 ```
 
+## If you are new to these words
+
+If you are not from computer science, the vocabulary can be confusing. In this package:
+
+- **Traversal** means "walking through nodes one by one".
+- A **parent** is the node directly above another node.
+- A **child** is a node directly below another node.
+- **Descendants** are children, children of children, etc.
+- **Ancestors** are parent, parent of parent, etc.
+
+You can think of this like a family tree.
+
+For the common cases:
+
+- Use [`descendants`](@ref) to move downward in the MTG.
+- Use [`ancestors`](@ref) to move upward in the MTG.
+- Add filters (`symbol`, `scale`, `filter_fun`) when you only need part of the MTG.
+
+## Traversal quick recipes
+
+These examples cover the most common requests:
+
+```@example usepkg
+node_5 = get_node(mtg, 5)
+
+# 1) Get one attribute for the whole subtree
+descendants(mtg, :Length)
+
+# 2) Get nodes instead of values
+descendants(mtg)
+
+# 3) Get one attribute from parents and grandparents
+ancestors(node_5, :Length)
+
+# 4) Filter by symbol and ignore nodes without the attribute
+descendants(mtg, :Length, symbol=:Leaf, ignore_nothing=true)
+```
+
+!!! tip
+    If you call the same traversal many times in a simulation loop, look at [Performance Considerations](@ref), especially in-place methods (`descendants!`, `ancestors!`).
+
 You can get all the attributes of a node using the [`node_attributes`](@ref) function:
 
 ```@example usepkg