forked from scikit-learn/scikit-learn
-
Notifications
You must be signed in to change notification settings - Fork 0
How to write docs
ogrisel edited this page Aug 18, 2011
·
11 revisions
Some guidelines on documenting estimators.
The class should have a docstring with the fields Parameters, Attributes, Examples, See also. Example:
class Foo (BaseEstimator):
"""C-Support Vector Classification.
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 fit 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 fit(self, X, Y):
"""Fit the SVM model to the given training data and parameters.
Give additional details on how the algorithm works (e.g. the objective
function) and some element to understand the space and time complexity.
Parameters
----------
X : array-like, shape = [n_samples, n_features]
Training vector, where n_samples in the number of samples and
n_features is the number of features.
Y : array, shape = [n_samples]
Target values (integers in classification, real numbers in
regression)
Returns
--------
self
"""The predict method should also be documented in a similar way:
def predict(self, X):
"""Predict class membership index for each input sample.
This function does classification on an array of
test vectors X.
Parameters
----------
X : array-like, shape = [n_samples, n_features]
Returns
-------
C : array, shape = [n_samples]
"""When documenting estimated parameters, they should be sourrunded by the characters `` , or sphinx will interpret them as a link
TODO