How to write docs

How to write documentation

Some guidelines on documenting the recommenders.

Class docstring

The class should have a docstring with the fields Parameters, Attributes, Examples, See also. Example:

 class FooRecommender (BaseRecommender):
    """
    Foo-Based Recommender.

    Parameters
    ----------

    C : float, optional (default=1.0)
        penalty parameter C of the error term.
    
    kernel : string, optional
         Description of this members.

    Attributes
    ----------

    `bar_` : array-like, shape = [n_features]
        Brief description of this attribute.



    Examples
    --------
    >>> clf = Foo()
    >>> clf.fit()
    []

    See also
    --------
    OtherClass
    """

The recommend method

The recommend method should also be documented, at least a description (even if it seems obvious) and the list of parameters and the return parameters. Something like

  def recommend(self,user_id,how_many,**params):
      """
      Return a list of recommended items, ordered from most strongly recommend to least.
       
      Parameters
      ----------
      user_id: int or string
               User for which recommendations are to be computed.
      how_many: int 
               Desired number of recommendations
      rescorer:  function, optional
               Rescoring function to apply before final list of recommendations.

     Returns
     --------
     self
      """

The estimate_preference method

The estimate_preference method should also be documented in a similar way:

  def estimate_preference(self,**params):
      """
      Return an estimated preference if the user has not expressed a preference for the item, or else the 
      user's actual preference for the item. If a preference cannot be estimated, returns None.
      
      Parameters
      ----------
      params: dict
         A set of parameters.


      Returns
      -------
      estimated_preference : float or None
      """

Misc

When documenting estimated parameters, they should be sourrunded by the characters `` , or sphinx will interpret them as a link

The RST docs

TODO