update docs, upgrade to documenter 1

docs/Project.toml

@@ -1,2 +1,5 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
+StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
+StatsFuns = "4c63d2b9-4356-54db-8cca-17b64c39e42c"

docs/make.jl

@@ -2,6 +2,7 @@ using Documenter
 using RankChoiceVoting
 
 makedocs(
+    warnonly = true,
     sitename = "RankChoiceVoting",
     format = Documenter.HTML(
         assets=[
@@ -29,7 +30,10 @@ makedocs(
                         "Mutual Majority" => "criteria/mutual_majority.md",
                         "Reversal Symmetry" => "criteria/reversalsymmetry.md",
                         "IIA" => "criteria/IIA.md"],
-        "API" => "api.md",
+        "Examples" => ["Spatial Model" => "simulations/spatial_model.md"],
+        "API" => ["Systems" => "api_systems.md",
+                 "Criteria" => "api_criteria.md"],
+        "Contributer Guide" => "contributer_guide.md"
     ]
 )
 

docs/src/api.md → docs/src/api_criteria.md

@@ -1,4 +1,5 @@
 # Criteria
+
 ```@autodocs
 Modules = [RankChoiceVoting]
 Order   = [:type,:function]
@@ -12,14 +13,4 @@ Pages = ["criteria/condorcet_loser.jl",
         "criteria/monotonicity.jl",
         "criteria/reversalsymmetry.jl",
     ]
-```
-# Systems 
-```@autodocs
-Modules = [RankChoiceVoting]
-Order   = [:type,:function]
-Private = false
-Pages = ["systems/Borda.jl",
-        "systems/Bucklin.jl",
-        "systems/instant_runoff.jl",
-    ]
 ```

docs/src/api_systems.md

@@ -0,0 +1,10 @@
+# Systems 
+```@autodocs
+Modules = [RankChoiceVoting]
+Order   = [:type,:function]
+Private = false
+Pages = ["systems/Borda.jl",
+        "systems/Bucklin.jl",
+        "systems/instant_runoff.jl",
+    ]
+```

docs/src/contributer_guide.md

@@ -0,0 +1,60 @@
+# Process
+
+Thank you for your interest in contributing to RankChoiceVoting. If you would like to contribute, please open an issue and propose your ideas.  
+
+# Style Guide
+
+In most cases, code written in RankChoiceVoting.jl follows the guidelines specified in the [blue style](https://github.com/invenia/BlueStyle) guide for Julia. Please use the blue style guide or existing code as a guide, and deviate from the guides only when there is a compelling reason to do so.
+
+# API 
+
+The basic API is summarized below. If you add a new voting system, it should work with the fairness criteria already established. By default, voting systems are assumed to violate fairness criteria. Consequentially, functions such as `satisfies` will manually check for violations. Use `property` to specify that a system is gaurunteed to satisfy a criterion, which will bypass the violatio check. As an example, consider:
+
+```julia 
+property(::MyCoolVotingSystem, ::Majority) = Holds()
+```
+Also, add new types to `src/constants.jl` to ensure they are included in the evaluation of methods `satisfies(system)` and `satisfies(criteria)`.
+## Types
+
+- `systems`: a set of rules for transforming individual rank choice votes into a societal ranking
+- `criteria`: fairness criteria against which a voting system is evaluated 
+
+## Functions
+
+The API uses the following methods:
+
+- `compute_ranks`: transforms a set of individual rank choices into a societal ranking
+- `evaluate_winner`: returns the winner(s) of an election
+- `satisfies`: evaluates whether a system satisfies a given criterion
+- `count_violations`: counts the number of violations of a criterion in a given set of rank choice votes
+
+
+# Documentation
+
+If you add a new fairness criterion or voting system, please provide examples based on existing examples. 
+
+## Docstrings
+
+At minimum, add doc strings to methods in the API. Adding docstrings for internal methods is encouraged. Please use the following template for docstrings:
+```julia 
+"""
+    satisfies(system::VotingSystem, criterion::Majority, rankings::Ranks; _...)
+
+Tests whether a voting system satisfies the majority criterion.
+
+# Arguments
+
+- `system::VotingSystem`: a voting system object
+- `criterion::Majority`: majority criterion object 
+- `rankings::Ranks`: a rank choice voting object consisting of rank counts and unique ranks 
+"""
+```
+Add any additional information that might be relevant to the user. 
+
+# API
+
+Only export (make public) types and methods that are intended for users. Other methods are implementational details for interal use. 
+
+# Unit tests
+
+Provide unit tests for most (if not all) methods. When possible, programatically test a method over a wide range of inputs. If you find a bug, write a unit test for the bug to prevent regressions. When possible, compare methods to those defined in established and trusted packages in other languages.  

docs/src/index.md

@@ -26,6 +26,8 @@ The API for RankChoiceVoting consists of three sets of types:
 
 ## Functions
 
+The API uses the following methods:
+
 - `compute_ranks`: transforms a set of individual rank choices into a societal ranking
 - `evaluate_winner`: returns the winner(s) of an election
 - `satisfies`: evaluates whether a system satisfies a given criterion

docs/src/simulations/spatial_model.md

@@ -0,0 +1,72 @@
+```@setup spatial_model
+using LinearAlgebra
+using Plots
+using RankChoiceVoting
+using Random
+using StatsBase
+```
+
+# Spatial Model Example
+
+The following example illustrates how to generate simulated preference profiles from a spatial model and evaluate whether the Borda count voting system satisfies independence of irrelevant alternatives (IIA). A spatial model describes the beliefs of voters as points in an n-dimensional space where each dimension represents a belief about a policy or value. Candidates are represented as points in the n-dimensional space. The model assumes voters rank order candidates as an increasing function of distance, where the minimum distance is ranked 1, the second shortest distances is ranked 2 and so forth. 
+
+## Load Dependencies
+
+The first step is to load the required dependencies.
+```@example spatial_model
+using LinearAlgebra
+using Plots
+using RankChoiceVoting
+using Random
+using StatsBase
+Random.seed!(54)
+```
+## Define Helper Functions
+
+In the code block below, we define two helper functions. The function `rank_candidates` computes the distance between a voter and the candidatess and returns a rank ordering based on distance. The function `select` returns the index associated with the most preferred candidate. 
+
+```@example spatial_model
+function rank_candidates(beliefs, candidates)
+    return competerank(map(c -> norm(beliefs .- c), candidates))
+end
+
+function select(beliefs, candidates)
+    _,choice = findmin(rank_candidates(beliefs, candidates))
+    return choice
+end
+```
+## Define Candidates
+
+Lets assume the belief space defined over $[0,1]^2$ and the candidates occupy the following positions in that space.
+```@example spatial_model
+candidates = [(.3,.3), (.3,.5),(.8,.5)]
+```
+The plot below illustrates the area of the belief space to which the canidates appeal. For example, voters in the top left quadrant will vote for candidate 2.
+```@example spatial_model
+points = [Tuple(rand(2)) for _ ∈ 1:10_000]
+first_choices = map(x -> select(x, candidates), points)
+scatter(points, lims=(0,1), grid=false, legendtitle="candidates", group=first_choices,  legend=:outerright)
+```
+
+## Define Voters
+Next, we will define a set of 100 voters by sampling uniformly over $[0,1]^2$:
+```@example spatial_model
+voters = [Tuple(rand(2)) for _ ∈ 1:100]
+votes = map(v -> rank_candidates(v, candidates), voters)
+ranks = Ranks(votes)
+```
+
+# Evaluate  
+The last code blocks tests whether the Borda count system satisisfies IIA for the simulated preference profile.
+
+```@example spatial_model
+satisfies(Borda(), IIA(), ranks)
+```
+
+In this case, it does satisfy IIA. Does hold in general? Let's call `satisfies` without the preference profile to answer that question. 
+
+```@example spatial_model
+satisfies(Borda(), IIA())
+```
+
+The result above indicates that there are some cases in which the Borda count system violates IIA.