Fix links (#1141)

jmaspons · Datseris · web-flow · commit 0479c38e366e · 2025-02-28T15:21:49.000Z
* Add URLs for links to Agents Example Zoo * Wrong section id specification * Fix or specify @ref where text value doesn't match (implicit) @id * Missing docs * Add @id and @ref * Typos and @ref missmatches * Remove reference to a missing section in the Tutorial * Add module in the @ref * Adress comments from @Datseris * Second round review * Update Project.toml --------- Co-authored-by: George Datseris <datseris.george@gmail.com>
diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "Agents"
 uuid = "46ada45e-f475-11e8-01d0-f70cc89e6671"
 authors = ["George Datseris", "Tim DuBois", "Aayush Sabharwal", "Ali Vahdati", "Adriano Meligrana"]
-version = "6.2.5"
+version = "6.2.6"
 
 [deps]
 CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"
diff --git a/docs/src/api.md b/docs/src/api.md
@@ -1,6 +1,6 @@
 # API
 
-The API of Agents.jl is defined on top of the fundamental structures [`AgentBasedModel`](@ref), [Space](@ref Space), [`AbstractAgent`](@ref) which are described in the [Tutorial](@ref) page.
+The API of Agents.jl is defined on top of the fundamental structures [`AgentBasedModel`](@ref), [Space](@ref available_spaces), [`AbstractAgent`](@ref) which are described in the [Tutorial](@ref) page.
 In this page we list the remaining API functions, which constitute the bulk of Agents.jl functionality.
 
 ## [AgentBasedModel](@id ABM_Implementations)
@@ -11,6 +11,7 @@ In this page we list the remaining API functions, which constitute the bulk of A
 
 ```@docs
 AgentBasedModel
+step!(::AgentBasedModel, args...)
 ```
 
 ### Discrete time models
@@ -108,7 +109,7 @@ get_direction
 ```
 
 ### Movement with paths
-For [`OpenStreetMapSpace`](@ref), and [`GridSpace`](@ref)/[`ContinuousSpace`](@ref) using [`Pathfinding.Pathfinder`](@ref), a special
+For [`OpenStreetMapSpace`](@ref), and [`GridSpace`](@ref)/[`ContinuousSpace`](@ref) using [`Pathfinding`](@ref), a special
 movement method is available.
 
 ```@docs
@@ -159,7 +160,7 @@ add_vertex!
 rem_vertex!
 ```
 
-## `ContinuousSpace` exclusives
+## [`ContinuousSpace` exclusives](@id ContinuosSpace_exclusives)
 ```@docs
 nearest_neighbor
 get_spatial_property
@@ -339,7 +340,7 @@ step!(model, agentstep, modelstep, 100; scheduler = ms)
 
 
 ### How to use `Distributed`
-To use the `parallel=true` option of [`ensemblerun!`](@ref) you need to load `Agents` and define your fundamental types at all processors. How to do this is shown in [Ensembles and distributed computing](@ref) section of Schelling's Segregation Model example. See also the [Performance Tips](@ref) page for parallelization.
+To use the `parallel=true` option of [`ensemblerun!`](@ref) you need to load `Agents` and define your fundamental types at all processors. See the [Performance Tips](@ref) page for parallelization.
 
 ## Path-finding
 ```@docs
diff --git a/docs/src/devdocs.md b/docs/src/devdocs.md
@@ -24,7 +24,7 @@ If you wish to do any development work, it is better to use
 git clone https://github.com/JuliaDynamics/Agents.jl.git --single-branch
 ```
 
-## [Creating a new model type](@ref make_new_model)
+## [Creating a new model type](@id make_new_model)
 
 Note that new model types target applications where a fundamentally different
 way to define the "time evolution" or "dynamic rule" is required.
@@ -47,7 +47,7 @@ default implementation that e.g., attempts to return a field named `:rng`.
 The rest of the methods by default return a "not implemented" error message
 (and those you also need to extend mandatorily).
 
-## [Creating a new space type](@ref make_new_space)
+## [Creating a new space type](@id make_new_space)
 
 Creating a new space type within Agents.jl is quite simple and requires the extension of only 5 methods to support the entire Agents.jl API. The exact specifications on how to create a new space type are contained within the source file: [`src/core/space_interaction_API.jl`](https://github.com/JuliaDynamics/Agents.jl/blob/main/src/core/space_interaction_API.jl).
 
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -92,7 +92,7 @@ Agents.jl was designed with the following philosophy in mind:
 
 
 
-There are multiple examples that highlight this core design principle, that one will quickly encounter when scanning through our [API](@ref) page. Here we just give two quick examples: first, there exists a universal function [`nearby_agents`](@ref), which returns the agents nearby a given agent and within a given "radius". What is special for this function, which is allowed by Julia's Multiple Dispatch, is that `nearby_agents` will work for any space type the model has, reducing the learning curve of finding neighbors in ABMs made with Agents.jl. An even better example is perhaps our treatment of spaces. A user may create an entirely new kind of space (e.g. one representing a planet, or whatever else) by only extending 5 functions, as discussed in our [Creating a new space type](@ref) documentation. Indeed, the simplicity of Agents.jl is due to the intuitive space-agnostic modelling approach we have implemented: agent actions are specified using generically named functions (such as "move agent" or "find nearby agents") that do not depend on the actual space the agents exist in, nor on the properties of the agents themselves. Overall this leads to ultra fast model prototyping where even changing the space the agents live in is matter of only a couple of lines of code.
+There are multiple examples that highlight this core design principle, that one will quickly encounter when scanning through our [API](@ref) page. Here we just give two quick examples: first, there exists a universal function [`nearby_agents`](@ref), which returns the agents nearby a given agent and within a given "radius". What is special for this function, which is allowed by Julia's Multiple Dispatch, is that `nearby_agents` will work for any space type the model has, reducing the learning curve of finding neighbors in ABMs made with Agents.jl. An even better example is perhaps our treatment of spaces. A user may create an entirely new kind of space (e.g. one representing a planet, or whatever else) by only extending 5 functions, as discussed in our [Creating a new space type](@ref make_new_space) documentation. Indeed, the simplicity of Agents.jl is due to the intuitive space-agnostic modelling approach we have implemented: agent actions are specified using generically named functions (such as "move agent" or "find nearby agents") that do not depend on the actual space the agents exist in, nor on the properties of the agents themselves. Overall this leads to ultra fast model prototyping where even changing the space the agents live in is matter of only a couple of lines of code.
 
 Many other agent-based modeling frameworks have been constructed to ease the process of building and analyzing ABMs (see e.g. [here](http://dx.doi.org/10.1016/j.cosrev.2017.03.001) for an outdated review), spanning a varying degree of complexity.
 In the page [ABM Framework Comparison](@ref) we compare how our design philosophy puts us into comparison with other well accepted ABM software.
diff --git a/docs/src/performance_tips.md b/docs/src/performance_tips.md
@@ -115,7 +115,7 @@ It might be tempting to represent this property as a specific type of agent like
 However, in Agents.jl this is not necessary and a much more performant approach can be followed.
 Specifically, you can represent this property as a standard Julia `Array` that is a property of the model. This will typically lead to a 5-10 fold increase in performance.
 
-For an example of how this is done, see the [Forest fire](@ref) model, which is a cellular automaton that has no agents in it, or the [Daisyworld](@ref) model, which has both agents as well as a spatial property represented by an `Array`.
+For an example of how this is done, see the [Forest fire](https://juliadynamics.github.io/AgentsExampleZoo.jl/dev/examples/forest_fire/) model, which is a cellular automaton that has no agents in it, or the [Daisyworld](https://juliadynamics.github.io/AgentsExampleZoo.jl/dev/examples/daisyworld/) model, which has both agents as well as a spatial property represented by an `Array`.
 
 ## [Multiple agent types: `@multiagent` versus `Union` types](@id multi_vs_union)
 
diff --git a/examples/event_rock_paper_scissors.jl b/examples/event_rock_paper_scissors.jl
@@ -222,7 +222,7 @@ end
 # ## Time evolution
 # %% #src
 
-# Time evolution for [`EventBasedABM`](@ref) is identical
+# Time evolution for [`EventQueueABM`](@ref) is identical
 # to that of [`StandardABM`](@ref), but time is continuous.
 # So, when calling `step!` we pass in a real time.
 
diff --git a/examples/measurements.jl b/examples/measurements.jl
@@ -3,8 +3,8 @@
 # [Measurements.jl](https://github.com/JuliaPhysics/Measurements.jl) provides automatic
 # error propagation, and integrates seamlessly with much of the Julia ecosystem.
 #
-# Here, we'll slightly modify the [Daisyworld](@ref) example, to simulate some measurement
-# uncertainty in our world's parameters.
+# Here, we'll slightly modify the [Daisyworld](https://juliadynamics.github.io/AgentsExampleZoo.jl/dev/examples/daisyworld/)
+# example, to simulate some measurement uncertainty in our world's parameters.
 #
 # ## Setup
 #
@@ -31,8 +31,8 @@ end
 # parameters with type `Measurement{Float64}` as well.
 #
 # Next, we'll implement all the important functions for DaisyWorld. If you want to know what
-# each of these functions do, see the [Daisyworld](@ref) example, as they are copied directly
-# from there.
+# each of these functions do, see the [Daisyworld](https://juliadynamics.github.io/AgentsExampleZoo.jl/dev/examples/daisyworld/)
+# example, as they are copied directly from there.
 
 using CairoMakie
 using Statistics: mean
@@ -168,8 +168,9 @@ end
 
 # ## Visualizing the Result
 #
-# Similar to the [Daisyworld](@ref) example, we will now check out how the surface temperature
-# and daisy count fares when solar luminosity ramps up.
+# Similar to the [Daisyworld](https://juliadynamics.github.io/AgentsExampleZoo.jl/dev/examples/daisyworld/)
+# example, we will now check out how the surface temperature and daisy count fares when solar
+# luminosity ramps up.
 #
 # First, some helper functions
 
diff --git a/examples/predator_prey.jl b/examples/predator_prey.jl
@@ -42,7 +42,7 @@
 # ## Making the model
 # First we define the agent types
 # (here you can see that it isn't really that much
-# of an advantage to have two different agent types. Like in the [Rabbit, Fox, Hawk](@ref)
+# of an advantage to have two different agent types. Like in the [Rabbit, Fox, Hawk](https://juliadynamics.github.io/Agents.jl/stable/examples/rabbit_fox_hawk/)
 # example, we could have only one type and one additional field to separate them.
 # Nevertheless, for the sake of example, we will use two different types.)
 using Agents, Random
diff --git a/src/core/agents.jl b/src/core/agents.jl
@@ -10,7 +10,7 @@ Agents participating in Agents.jl simulations are instances of user-defined type
 are subtypes of `AbstractAgent`.
 
 Your agent type(s) **must have** the `id::Int` field as first field.
-If any space is used (see [Available spaces](@ref)), a `pos` field of appropriate type
+If any space is used (see [Available spaces](@ref available_spaces)), a `pos` field of appropriate type
 is also mandatory. The core model structure, and each space,
 may also require additional fields that may,
 or may not, be communicated as part of the public API.
@@ -265,7 +265,7 @@ This means that all "subtypes" are enclosed in the overarching type. Then, You c
 distinguish them on the basis of `typeof`, but need to use instead the `variantof`
 function. The `allvariants` function for a convenient way to obtain all variants types.
 
-See the [Tutorial](@ref) or the [performance comparison versus `Union` types](@ref multiagent_vs_union)
+See the [Tutorial](@ref) or the [performance comparison versus `Union` types](@ref multi_vs_union)
 for why it is often better to use `@multiagent` than making multiple agent types.
 
 `@multiagent` is based on LightSumTypes.jl.
diff --git a/src/core/model_abstract.jl b/src/core/model_abstract.jl
@@ -35,6 +35,7 @@ see [the corresponding entry in the developer documentation](@ref make_new_model
 
 ## Interface of `AgentBasedModel`
 
+- `step!(model, args...)` progress the model forwards in time.
 - `model[id]` returns the agent with given `id`.
 - `abmproperties(model)` returns the `properties` container storing model-level properties.
 - `model.property`:  If the model `properties` is a dictionary with
diff --git a/src/core/model_event_queue.jl b/src/core/model_event_queue.jl
@@ -5,7 +5,7 @@ using DataStructures: PriorityQueue
 """
     AgentEvent(; action!, propensity, kinds, timing)
 
-An event instance that can be given to [`EventQeueABM`](@ref).
+An event instance that can be given to [`EventQueueABM`](@ref).
 
 - `action! = dummystep`: is the function `action!(agent, model)` that will
   act on the agent the event corresponds to. This keyword is mandatory.
@@ -115,7 +115,7 @@ The model expects agents of type `AgentType(s)` living in the given `space`.
 `AgentType(s)` is the result of [`@agent`](@ref) or `@multiagent` or
 a `Union` of agent types.
 
-`space` is a subtype of `AbstractSpace`, see [Space](@ref Space) for all available spaces.
+`space` is a subtype of `AbstractSpace`, see [Space](@ref available_spaces) for all available spaces.
 
 `events` is a container of instances of [`AgentEvent`](@ref),
 which are the events that are scheduled and then affect agents.
@@ -140,7 +140,7 @@ can be evolved in time.
 
 
 !!! warn "No IO yet"
-    This model does not yet support IO operations such as [`save_checkpoint`](@ref).
+    This model does not yet support IO operations such as [`save_checkpoint`](@ref AgentsIO.save_checkpoint).
     Pull Requests that implement this are welcomed!
 """
 function EventQueueABM(
diff --git a/src/core/model_standard.jl b/src/core/model_standard.jl
@@ -57,7 +57,7 @@ The model expects agents of type `AgentType(s)` living in the given `space`.
 `AgentType(s)` is the result of [`@agent`](@ref) or `@multiagent` or
 a `Union` of agent types.
 
-`space` is a subtype of `AbstractSpace`, see [Space](@ref Space) for all available spaces.
+`space` is a subtype of `AbstractSpace`, see [Space](@ref available_spaces) for all available spaces.
 If it is omitted then all agents are virtually in one position and there is no spatial
 structure.
 Spaces are mutable objects and are not designed to be shared between models.
diff --git a/src/simulations/collect.jl b/src/simulations/collect.jl
@@ -200,7 +200,7 @@ should_we_collect(s, ds, model, when::Function) = when(model, s)
 """
     offline_run!(model, t::Union{Real, Function}; kwargs...)
 
-Do the same as [`run`](@ref), but instead of collecting all the data into an in-memory
+Do the same as [`run!`](@ref), but instead of collecting all the data into an in-memory
 dataframe, write the output to a file after collecting data `writing_interval` times and
 empty the dataframe after each write.
 Useful when the amount of collected data is expected to exceed the memory available
diff --git a/src/simulations/ensemblerun.jl b/src/simulations/ensemblerun.jl
@@ -16,7 +16,7 @@ If you want to scan parameters and at the same time run multiple simulations at
 parameter combination, simply use `seed` as a parameter, and use that parameter to
 tune the model's initial random seed and/or agent distribution.
 
-See example usage in [Schelling's segregation model](@ref).
+See example usage in [Schelling's segregation model](@ref Tutorial).
 
 ## Keywords
 The following keywords modify the `ensemblerun!` function:
diff --git a/src/simulations/paramscan.jl b/src/simulations/paramscan.jl
@@ -47,7 +47,7 @@ The `adata, mdata` lists shouldn't contain the parameters that are already in
 the `parameters` dictionary to avoid duplication.
 
 ## Example
-A runnable example that uses `paramscan` is shown in [Schelling's segregation model](@ref).
+A runnable example that uses `paramscan` is shown in [Schelling's segregation model](@ref Tutorial).
 There, we define
 ```julia
 function initialize(; numagents = 320, griddims = (20, 20), min_to_be_happy = 3)
diff --git a/src/spaces/continuous.jl b/src/spaces/continuous.jl
@@ -56,7 +56,7 @@ the position is automatically mapped into the discretization represented by the
 Use [`get_spatial_property`](@ref) to access spatial properties in conjunction with
 `ContinuousSpace`.
 
-See also [Continuous space exclusives](@ref) on the online docs for more functionality.
+See also [`ContinuousSpace` exclusives](@ref ContinuosSpace_exclusives) on the online docs for more functionality.
 An example using continuous space is the [Flocking model](@ref).
 
 ## Distance specification
@@ -398,7 +398,8 @@ The following keywords can be used:
 - `search = :exact` decides how to find nearby IDs in the `:all, :types` cases. 
   Must be `:exact` or `:approximate`.
 
-Example usage in [https://juliadynamics.github.io/AgentsExampleZoo.jl/dev/examples/growing_bacteria/](@ref).
+Example usage in [Bacterial Growth](https://juliadynamics.github.io/AgentsExampleZoo.jl/dev/examples/growing_bacteria/)
+model.
 
 !!! note "Better performance with CellListMap.jl"
     Notice that in most applications that [`interacting_pairs`](@ref) is useful, there is
diff --git a/src/spaces/grid_multi.jl b/src/spaces/grid_multi.jl
@@ -19,7 +19,7 @@ Optionally decide whether the space will be periodic and what will be the distan
 The position type for this space is `NTuple{D, Int}`, use [`GridAgent`](@ref) for convenience.
 Valid positions have indices in the range `1:d[i]` for the `i`-th dimension.
 
-An example using `GridSpace` is [Schelling's segregation model](@ref).
+An example using `GridSpace` is [Schelling's segregation model](@ref Tutorial).
 
 ## Distance specification
 The typical terminology when searching neighbors in agent based modelling is
diff --git a/src/spaces/openstreetmap.jl b/src/spaces/openstreetmap.jl
@@ -42,7 +42,7 @@ The map is stored as a `Graph` by `LightOSM`, and hence each node also has a ver
 corresponding to the vertex representing it in this graph. Hence each node can be referred
 to by either the node ID or its graph index, and we can convert either way, using
 the function `LightOSM.index_to_node`.
-We use graph vertex indices consistently in [`OSMSpace`](@ref), because
+We use graph vertex indices consistently in [`OpenStreetMapSpace`](@ref OSM.OpenStreetMapSpace), because
 we access graph data more often than OSM data.
 
 ## Fields of `OpenStreetMapPath`
@@ -94,7 +94,7 @@ The distance travelled is in the units of `weight_type`. This ensures that the m
 is a *continuous* kind of space, as an agent can truly be at any possible point on
 an existing road.
 
-Use [`OSMAgent`](@ref) for convenience.
+Use [`OSMAgent`](@ref OSM.OSMAgent) for convenience.
 
 ## Obtaining map files
 Maps files can be downloaded using the functions provided by
@@ -151,7 +151,7 @@ end
 
 """
     OSMAgent <: AbstractAgent
-The minimal agent struct for usage with [`OpenStreetMapSpace`](@ref).
+The minimal agent struct for usage with [`OpenStreetMapSpace`](@ref OSM.OpenStreetMapSpace).
 It has an additional field `pos::Tuple{Int,Int,Float64}`. See also [`@agent`](@ref).
 """
 @agent struct OSMAgent(NoSpaceAgent)
@@ -165,7 +165,7 @@ Download a small test map of [Göttingen](https://www.openstreetmap.org/export#m
 as an artifact. Return a path to the downloaded file.
 
 Using this map requires `network_type = :none` to be passed as a keyword
-to [`OSMSpace`](@ref). The unit of distance used for this map is `:time`.
+to [`OpenStreetMapSpace`](@ref OSM.OpenStreetMapSpace). The unit of distance used for this map is `:time`.
 """
 test_map() = joinpath(artifact"osm_map_gottingen", "osm_map_gottingen.json")
 
diff --git a/src/submodules/pathfinding/Pathfinding.jl b/src/submodules/pathfinding/Pathfinding.jl
@@ -16,7 +16,7 @@ precalculated path using the [`move_along_route!`](@ref) function.
 
 Refer to the [Maze Solver](https://juliadynamics.github.io/AgentsExampleZoo.jl/dev/examples/maze/),
 [Mountain Runners](https://juliadynamics.github.io/AgentsExampleZoo.jl/dev/examples/runners/)
-and [Rabbit, Fox, Hawk](@ref)
+and [Rabbit, Fox, Hawk](https://juliadynamics.github.io/Agents.jl/stable/examples/rabbit_fox_hawk/)
 examples using path-finding and see the available functions below as well.
 """
 module Pathfinding
diff --git a/src/submodules/pathfinding/astar.jl b/src/submodules/pathfinding/astar.jl
@@ -59,7 +59,8 @@ to specify the level of discretisation of the space.
   metric used to approximate the distance between any two points.
 
 Utilization of all features of `AStar` occurs in the
-[3D Mixed-Agent Ecosystem with Pathfinding](@ref) example.
+[3D Mixed-Agent Ecosystem with Pathfinding](@id rabbit_fox_hawk)
+example.
 """
 function AStar(
     dims::NTuple{D,T};
diff --git a/src/submodules/schedulers.jl b/src/submodules/schedulers.jl
@@ -25,7 +25,7 @@ Schedulers have many purposes:
 1. Can be given in [`StandardABM`](@ref) as a default scheduler.
    This functionality is only meaningful when the `agent_step!` has been configured.
    The function `schedule(model)` will return the scheduled IDs.
-2. Can be used by a user when performing [manual scheduling](@ref manual_scheduling)
+2. Can be used by a user when performing [manual scheduling](@ref Advanced_scheduling)
    in case `agent_step!` has not been configured.
 3. Can be used to globally filter agents by type/property/whatever. For example,
    one can use the [`ByProperty`](@ref) scheduler to simply obtain
@@ -156,7 +156,7 @@ A scheduler useful only for mixed agent models using `Union` types.
   Otherwise returns agent IDs grouped in order of appearance in the `Union`.
 - `shuffle_agents = true` randomizes the order of agents within each group, `false` returns
   the default order of the container (equivalent to [`Schedulers.fastest`](@ref)).
-- `agent_union` is a `Union` of all valid agent types (as passed to [`ABM`](@ref))
+- `agent_union` is a `Union` of all valid agent types (as passed to [`ABM`](@ref ABM_Implementations))
 
 
     Schedulers.ByType((C, B, A), shuffle_agents::Bool)

Original file line number	Diff line number	Diff line change
`@@ -3,8 +3,8 @@`
`3`	`3`	`# [Measurements.jl](https://github.com/JuliaPhysics/Measurements.jl) provides automatic`
`4`	`4`	`# error propagation, and integrates seamlessly with much of the Julia ecosystem.`
`5`	`5`	`#`
`6`		`-# Here, we'll slightly modify the [Daisyworld](@ref) example, to simulate some measurement`
`7`		`-# uncertainty in our world's parameters.`
	`6`	`+# Here, we'll slightly modify the [Daisyworld](https://juliadynamics.github.io/AgentsExampleZoo.jl/dev/examples/daisyworld/)`
	`7`	`+# example, to simulate some measurement uncertainty in our world's parameters.`
`8`	`8`	`#`
`9`	`9`	`# ## Setup`
`10`	`10`	`#`
`@@ -31,8 +31,8 @@ end`
`31`	`31`	# parameters with type `Measurement{Float64}` as well.
`32`	`32`	`#`
`33`	`33`	`# Next, we'll implement all the important functions for DaisyWorld. If you want to know what`
`34`		`-# each of these functions do, see the [Daisyworld](@ref) example, as they are copied directly`
`35`		`-# from there.`
	`34`	`+# each of these functions do, see the [Daisyworld](https://juliadynamics.github.io/AgentsExampleZoo.jl/dev/examples/daisyworld/)`
	`35`	`+# example, as they are copied directly from there.`
`36`	`36`
`37`	`37`	`using CairoMakie`
`38`	`38`	`using Statistics: mean`
`@@ -168,8 +168,9 @@ end`
`168`	`168`
`169`	`169`	`# ## Visualizing the Result`
`170`	`170`	`#`
`171`		`-# Similar to the [Daisyworld](@ref) example, we will now check out how the surface temperature`
`172`		`-# and daisy count fares when solar luminosity ramps up.`
	`171`	`+# Similar to the [Daisyworld](https://juliadynamics.github.io/AgentsExampleZoo.jl/dev/examples/daisyworld/)`
	`172`	`+# example, we will now check out how the surface temperature and daisy count fares when solar`
	`173`	`+# luminosity ramps up.`
`173`	`174`	`#`
`174`	`175`	`# First, some helper functions`
`175`	`176`