[WIP] Refactor documentation API Reference for gensim.summarization

gensim/summarization/bm25.py

@@ -3,20 +3,72 @@
 #
 # Licensed under the GNU LGPL v2.1 - http://www.gnu.org/licenses/lgpl.html
 
+"""This module contains function of computing BM25 scores for documents in 
+corpus and helper class `BM25` used in calculations.
+
+
+Example:
+--------
+>>> import numpy as np
+>>> from gensim.summarization.bm25 import get_bm25_weights
+>>> corpus = [
+>>>     ["black", "cat", "white", "cat"],
+>>>     ["cat", "outer", "space"],
+>>>     ["wag", "dog"]
+>>> ]
+>>> np.round(get_bm25_weights(corpus), 3)
+array([[ 1.282,  0.182,  0.   ],
+       [ 0.13 ,  1.113,  0.   ],
+       [ 0.   ,  0.   ,  1.022]])
+
+Data:
+-----
+.. data:: PARAM_K1 - free smoothing parameter for BM25.
+.. data:: PARAM_B - free smoothing parameter for BM25.
+.. data:: EPSILON - constant used for negative idf of document in corpus.
+"""
+
+
 import math
 from six import iteritems
 from six.moves import xrange
 
 
-# BM25 parameters.
 PARAM_K1 = 1.5
 PARAM_B = 0.75
 EPSILON = 0.25
 
 
 class BM25(object):
+    """Implementation of Best Matching 25 ranking function.
+
+    Attributes
+    ----------
+    corpus_size : int
+        Size of corpus (number of documents).
+    avgdl : float
+        Average length of document in `corpus`.
+    corpus : list of (list of str)
+        Corpus of documents.
+    f : list of dict
+        Terms frequencies for each document in `corpus`.
+    df : dict
+        Terms frequencies for whole `corpus`.
+    idf : dict
+        Inverse document frequency.
+
+    """
+
 
     def __init__(self, corpus):
+        """Presets atributes and runs initialize() function.
+
+        Parameters
+        ----------
+        corpus : list of (list of str)
+            Corpus of documents.
+
+        """
         self.corpus_size = len(corpus)
         self.avgdl = sum(float(len(x)) for x in corpus) / self.corpus_size
         self.corpus = corpus
@@ -25,7 +77,12 @@ def __init__(self, corpus):
         self.idf = {}
         self.initialize()
 
+
     def initialize(self):
+        """Calculates frequncies of terms in documents and in corpus. Also
+        computes inverse document frequncies.
+
+        """
         for document in self.corpus:
             frequencies = {}
             for word in document:
@@ -42,7 +99,26 @@ def initialize(self):
         for word, freq in iteritems(self.df):
             self.idf[word] = math.log(self.corpus_size - freq + 0.5) - math.log(freq + 0.5)
 
+
     def get_score(self, document, index, average_idf):
+        """Computes BM25 score of given `document` in relation to item of corpus
+        selected by `index`.
+
+        Parameters
+        ----------
+        document : list of str
+            Document to be scored.
+        index : integer
+            Index of document in corpus selected to score with `document`.
+        average_idf : float
+            Average idf in corpus.
+
+        Returns
+        -------
+        float
+            BM25 score.
+
+        """
         score = 0
         for word in document:
             if word not in self.f[index]:
@@ -52,7 +128,24 @@ def get_score(self, document, index, average_idf):
                       / (self.f[index][word] + PARAM_K1 * (1 - PARAM_B + PARAM_B * self.corpus_size / self.avgdl)))
         return score
 
+
     def get_scores(self, document, average_idf):
+        """Computes and returns BM25 scores of given `document` in relation to 
+        every item in corpus. 
+
+        Parameters
+        ----------
+        document : list of str
+            Document to be scored.
+        average_idf : float
+            Average idf in corpus.
+
+        Returns
+        -------
+        list of float
+            BM25 scores.
+
+        """
         scores = []
         for index in xrange(self.corpus_size):
             score = self.get_score(document, index, average_idf)
@@ -61,6 +154,20 @@ def get_scores(self, document, average_idf):
 
 
 def get_bm25_weights(corpus):
+    """Returns BM25 scores (weights) of documents in corpus. Each document
+    has to be weighted with every document in given corpus. 
+
+    Parameters
+    ----------
+    corpus : list of (list of str)
+        Corpus of documents.
+
+    Returns
+    -------
+    list of (list of float)
+        BM25 scores.
+
+    """
     bm25 = BM25(corpus)
     average_idf = sum(float(val) for val in bm25.idf.values()) / len(bm25.idf)
 

gensim/summarization/commons.py

@@ -3,10 +3,46 @@
 #
 # Licensed under the GNU LGPL v2.1 - http://www.gnu.org/licenses/lgpl.html
 
+"""This module provides functions of creatinf graph from sequence of values and
+removing of unreachable nodes.
+
+
+Examples
+--------
+
+Create simple graph and add edges. Let's kake a look at nodes.
+
+>>> gg = build_graph(['Felidae', 'Lion', 'Tiger', 'Wolf'])
+>>> gg.add_edge(("Felidae", "Lion"))
+>>> gg.add_edge(("Felidae", "Tiger"))
+>>> gg.nodes()
+['Felidae', 'Lion', 'Tiger', 'Wolf']
+
+Remove nodes with no edges.
+
+>>> remove_unreachable_nodes(gg)
+>>> gg.nodes()
+['Felidae', 'Lion', 'Tiger']
+
+"""
+
 from gensim.summarization.graph import Graph
 
 
 def build_graph(sequence):
+    """Creates and returns graph with given sequence of values.
+
+    Parameters
+    ----------
+    sequence : list
+        Sequence of values.
+
+    Returns
+    -------
+    Graph
+        Created graph.
+
+    """
     graph = Graph()
     for item in sequence:
         if not graph.has_node(item):
@@ -15,6 +51,15 @@ def build_graph(sequence):
 
 
 def remove_unreachable_nodes(graph):
+    """Removes unreachable nodes (nodes with no edges). Works inplace.
+
+    Parameters
+    ----------
+    graph : Graph
+        Given graph.
+
+    """
+
     for node in graph.nodes():
         if sum(graph.edge_weight((node, other)) for other in graph.neighbors(node)) == 0:
             graph.del_node(node)