add component documentation

docs/guide/index.rst

@@ -28,6 +28,8 @@ guide to how to use LensKit for research, education, and other purposes.
 
     conventions
     scorers
+    rankers
+    other-components
 
 .. toctree::
     :caption: Experiments

docs/guide/other-components.rst

@@ -0,0 +1,26 @@
+Other Components
+================
+
+LensKit provides a number of other components; they are detailed in the API reference,
+but a few that are useful in assembling useful pipelines include:
+
+Candidate Selectors
+~~~~~~~~~~~~~~~~~~~
+
+.. autosummary::
+    :nosignatures:
+
+    lenskit.basic.UnratedTrainingItemsCandidateSelector
+    lenskit.basic.AllTrainingItemsCandidateSelector
+
+History Lookup
+~~~~~~~~~~~~~~
+
+LensKit pipelines use a history lookup component to obtain user profile data
+when the recommender is called with only a user ID, so they do not need to
+repeat that logic in each component.
+
+.. autosummary::
+    :nosignatures:
+
+    lenskit.basic.UserTrainingHistoryLookup

docs/guide/rankers.rst

@@ -0,0 +1,26 @@
+.. _rankers:
+
+Ranking Algorithms
+==================
+
+LensKit provides several ranking components that rank items.
+
+The usual design for a ranker is to take as input a list of items named `items`,
+usually with scores (typically the output of a :ref:`scoring model <scorers>`),
+and possibly the query, and return an ordered item list.  Rankers can also take
+ranked inputs for re-ranking.  By convention, they are named ``XYZRanker``.
+
+Top-N Ranking
+~~~~~~~~~~~~~
+
+Classic top-*N* ranking is provided by :class:`lenskit.basic.TopNRanker`. The
+standard pipelines configured by :class:`~lenskit.pipeline.RecPipelineBuilder`
+use this ranker by default.
+
+Stochastic Ranking
+~~~~~~~~~~~~~~~~~~
+
+- :class:`lenskit.basic.SoftmaxRanker` computes a randomized Plackett-Luce
+  ranking, where each item is selected with probability proportional to its
+  score.
+- :class:`lenskit.basic.RandomSelector` selects items uniformly at random.

docs/guide/scorers.rst

@@ -1,11 +1,15 @@
+.. _scorers:
+
 Scoring Models
 ==============
 
 Most recommendation pipelines are built around a *scoring model* that scores
 items for a recommendation query (e.g., user).  Standard top-*N* recommendation
 uses these scores to rank items, and they can be used as inputs into other
 techniques such as samplers and rerankers.  Scorers are almost always
-:class:`~lenskit.pipeline.Trainable`, and by convention are named `XYZScorer`.
+:class:`~lenskit.pipeline.Trainable`, and by convention are named ``XYZScorer``.
+They typically take two inputs, the query (`query`) and the list of items to
+score (`items`).
 
 Scoring models are not limited to traditional pointwise scoring models such as
 matrix factorization.  Many learning-to-rank models are also implemented as
@@ -32,3 +36,15 @@ Classical Collaborative Filters
     lenskit.als.ImplicitMFScorer
     lenskit.sklearn.svd.BiasedSVDScorer
     lenskit.funksvd.FunkSVDScorer
+
+
+Utility Scorers
+~~~~~~~~~~~~~~~
+
+These scorers are used to compose more sophisticated pipelines, usually
+involving multiple pipelines.
+
+.. autosummary::
+    :nosignatures:
+
+    lenskit.basic.FallbackScorer