From 615824b0a726df6fc34bd07309edc665df2f7d96 Mon Sep 17 00:00:00 2001 From: adrinjalali Date: Thu, 11 Oct 2018 15:33:38 +0200 Subject: [PATCH 1/7] add example of a good docstring for defaults and examples --- doc/developers/contributing.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/developers/contributing.rst b/doc/developers/contributing.rst index 8360b2f3bb331..a3d1cfb204551 100644 --- a/doc/developers/contributing.rst +++ b/doc/developers/contributing.rst @@ -517,6 +517,10 @@ Finally, follow the formatting rules below to make it consistently good: * For "References" in docstrings, see the Silhouette Coefficient (:func:`sklearn.metrics.silhouette_score`). + * For specifying parameter default values and including a minimal + working example in the "Examples" section see the LinearSVC + (:class:`sklearn.svm.LinearSVC`) + Generated documentation on CircleCI ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 71cb6b33c94497d4682e5a67456d8bb0733d26d1 Mon Sep 17 00:00:00 2001 From: adrinjalali Date: Sun, 28 Jul 2019 16:30:19 +0200 Subject: [PATCH 2/7] trying Thomas's proposal --- doc/developers/contributing.rst | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/doc/developers/contributing.rst b/doc/developers/contributing.rst index e63917ca15130..41b9032e6cd47 100644 --- a/doc/developers/contributing.rst +++ b/doc/developers/contributing.rst @@ -603,14 +603,28 @@ Finally, follow the formatting rules below to make it consistently good: SelectKBest : Select features based on the k highest scores. SelectFpr : Select features based on a false positive rate test. +* When documenting the parameters and attributes, have the following in mind: + + 1. Do not use optional. Use `default=`. `str {'a', 'b'} or float, default=1.0` + 2. Python basic types. (`bool` instead of `boolean`) + 3. When defining 1-D shape, use parenthesis. `array-like shape=(n_samples,), None, default=None`. + 4. When defining 2-D shape, use parenthesis. `array-like shape=(n_samples, n_features)`. + 5. str with multiple options: `input: {'log', 'squared', 'multinomial'}` + 6. Only use `or` for separating types. `float, int or None, default=None` + 7. Only use comma to separate types. Information such as `shape` or `string` + options are defined together. Here is an extreme example: + + ``` + {'a', 'b'}, float, int, array-like shape=(n_samples,) or None, default=None + ``` + + 8. When supporting array-like and sparse matrix use: + `{array-like, sparse matrix} shape=(n_samples, n_features)` + * For unwritten formatting rules, try to follow existing good works: * For "References" in docstrings, see the Silhouette Coefficient (:func:`sklearn.metrics.silhouette_score`). - * For specifying parameter default values and including a minimal - working example in the "Examples" section see the LinearSVC - (:class:`sklearn.svm.LinearSVC`) - * When editing reStructuredText (``.rst``) files, try to keep line length under 80 characters when possible (exceptions include links and tables). From 802385183b6ac383f8a1c6d41f51a7e34f8d1fc5 Mon Sep 17 00:00:00 2001 From: adrinjalali Date: Thu, 1 Aug 2019 13:09:30 +0200 Subject: [PATCH 3/7] apply comments, add example --- doc/developers/contributing.rst | 33 +++++++++++++++++++++++---------- 1 file changed, 23 insertions(+), 10 deletions(-) diff --git a/doc/developers/contributing.rst b/doc/developers/contributing.rst index 41b9032e6cd47..94c75915e2cef 100644 --- a/doc/developers/contributing.rst +++ b/doc/developers/contributing.rst @@ -603,23 +603,36 @@ Finally, follow the formatting rules below to make it consistently good: SelectKBest : Select features based on the k highest scores. SelectFpr : Select features based on a false positive rate test. -* When documenting the parameters and attributes, have the following in mind: +* When documenting the parameters and attributes, here is a list of some good + examples:: - 1. Do not use optional. Use `default=`. `str {'a', 'b'} or float, default=1.0` + some_param : {'hello', 'goodbye'}, bool or int, default=True + The parameter description goes here, which can be either a string + literal (either `hello` or `goodbye`), a bool, or an int. The default + value is True. + + array_parameter : {array-like, sparse matrix, dataframe} of shape (n_samples, n_features) or (n_samples,) + This parameter accepts a data in either of the mentioned forms, with one + of the mentioned shapes. + +In general have the following in mind: + + 1. Do not use optional. Use `default=`. 2. Python basic types. (`bool` instead of `boolean`) - 3. When defining 1-D shape, use parenthesis. `array-like shape=(n_samples,), None, default=None`. - 4. When defining 2-D shape, use parenthesis. `array-like shape=(n_samples, n_features)`. + 3. When defining 1-D shape, use parenthesis. `array-like of shape (n_samples,), None, default=None`. + 4. When defining 2-D shape, use parenthesis. `array-like of shape (n_samples, n_features)`. 5. str with multiple options: `input: {'log', 'squared', 'multinomial'}` 6. Only use `or` for separating types. `float, int or None, default=None` 7. Only use comma to separate types. Information such as `shape` or `string` - options are defined together. Here is an extreme example: + options are defined together. Here is an extreme example:: + + {'a', 'b'}, float, int, array-like shape=(n_samples,) or None, default=None - ``` - {'a', 'b'}, float, int, array-like shape=(n_samples,) or None, default=None - ``` + 8. Array or matrix-like data can be a subset of + `{array-like, ndarray, smarse matrix, dataframe}`. An example supporting two + of them would be:: - 8. When supporting array-like and sparse matrix use: - `{array-like, sparse matrix} shape=(n_samples, n_features)` + `{array-like, sparse matrix} shape=(n_samples, n_features)` * For unwritten formatting rules, try to follow existing good works: From 1ece81a1d4233c04739ee6466498c1e97203f883 Mon Sep 17 00:00:00 2001 From: adrinjalali Date: Thu, 1 Aug 2019 18:59:48 +0200 Subject: [PATCH 4/7] further simplify and clarify instructions --- doc/developers/contributing.rst | 22 ++++++++-------------- 1 file changed, 8 insertions(+), 14 deletions(-) diff --git a/doc/developers/contributing.rst b/doc/developers/contributing.rst index 94c75915e2cef..f31388eff957d 100644 --- a/doc/developers/contributing.rst +++ b/doc/developers/contributing.rst @@ -617,20 +617,14 @@ Finally, follow the formatting rules below to make it consistently good: In general have the following in mind: - 1. Do not use optional. Use `default=`. - 2. Python basic types. (`bool` instead of `boolean`) - 3. When defining 1-D shape, use parenthesis. `array-like of shape (n_samples,), None, default=None`. - 4. When defining 2-D shape, use parenthesis. `array-like of shape (n_samples, n_features)`. - 5. str with multiple options: `input: {'log', 'squared', 'multinomial'}` - 6. Only use `or` for separating types. `float, int or None, default=None` - 7. Only use comma to separate types. Information such as `shape` or `string` - options are defined together. Here is an extreme example:: - - {'a', 'b'}, float, int, array-like shape=(n_samples,) or None, default=None - - 8. Array or matrix-like data can be a subset of - `{array-like, ndarray, smarse matrix, dataframe}`. An example supporting two - of them would be:: + 1. Python basic types. (`bool` instead of `boolean`) + 2. Use parenthesis for defining shapes: `array-like of shape (n_samples,)` + or `array-like of shape (n_samples, n_features)` + 3. str with multiple options: `input: {'log', 'squared', 'multinomial'}` + 4. 1D or 2D data can be a subset of + `{array-like, ndarray, sparse matrix, dataframe}`. Note that `array-like` + can also be a `list`, while `ndarray` is explicitly only a `numpy.ndarray`. + An example supporting two of them would be:: `{array-like, sparse matrix} shape=(n_samples, n_features)` From 76a72738add220255e64785f6b73b983352bf4da Mon Sep 17 00:00:00 2001 From: adrinjalali Date: Mon, 5 Aug 2019 14:09:37 +0200 Subject: [PATCH 5/7] add default and an easy example --- doc/developers/contributing.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/doc/developers/contributing.rst b/doc/developers/contributing.rst index f31388eff957d..29dd8426ca031 100644 --- a/doc/developers/contributing.rst +++ b/doc/developers/contributing.rst @@ -606,14 +606,18 @@ Finally, follow the formatting rules below to make it consistently good: * When documenting the parameters and attributes, here is a list of some good examples:: + n_clusters : int, default=3 + The number of clusters detected by the algorithm. + some_param : {'hello', 'goodbye'}, bool or int, default=True The parameter description goes here, which can be either a string literal (either `hello` or `goodbye`), a bool, or an int. The default value is True. array_parameter : {array-like, sparse matrix, dataframe} of shape (n_samples, n_features) or (n_samples,) - This parameter accepts a data in either of the mentioned forms, with one - of the mentioned shapes. + This parameter accepts data in either of the mentioned forms, with one + of the mentioned shapes. The default value is + `np.ones(shape=(n_samples,))`. In general have the following in mind: From 19ba1453105612189ab238a36ad660f7e92dd1ee Mon Sep 17 00:00:00 2001 From: adrinjalali Date: Mon, 5 Aug 2019 14:10:35 +0200 Subject: [PATCH 6/7] tab -> spaces --- doc/developers/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/developers/contributing.rst b/doc/developers/contributing.rst index f6f40b85e94a1..1dcae20e50861 100644 --- a/doc/developers/contributing.rst +++ b/doc/developers/contributing.rst @@ -610,7 +610,7 @@ Finally, follow the formatting rules below to make it consistently good: The number of clusters detected by the algorithm. some_param : {'hello', 'goodbye'}, bool or int, default=True - The parameter description goes here, which can be either a string + The parameter description goes here, which can be either a string literal (either `hello` or `goodbye`), a bool, or an int. The default value is True. From 0256ea1e4056d7f77c68bd07710a8f996d39f11f Mon Sep 17 00:00:00 2001 From: adrinjalali Date: Wed, 7 Aug 2019 15:36:57 +0200 Subject: [PATCH 7/7] address comments --- doc/developers/contributing.rst | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/doc/developers/contributing.rst b/doc/developers/contributing.rst index 1dcae20e50861..3c5146ad9d684 100644 --- a/doc/developers/contributing.rst +++ b/doc/developers/contributing.rst @@ -603,8 +603,8 @@ Finally, follow the formatting rules below to make it consistently good: SelectKBest : Select features based on the k highest scores. SelectFpr : Select features based on a false positive rate test. -* When documenting the parameters and attributes, here is a list of some good - examples:: +* When documenting the parameters and attributes, here is a list of some + well-formatted examples:: n_clusters : int, default=3 The number of clusters detected by the algorithm. @@ -621,16 +621,14 @@ Finally, follow the formatting rules below to make it consistently good: In general have the following in mind: - 1. Python basic types. (`bool` instead of `boolean`) - 2. Use parenthesis for defining shapes: `array-like of shape (n_samples,)` - or `array-like of shape (n_samples, n_features)` - 3. str with multiple options: `input: {'log', 'squared', 'multinomial'}` + 1. Use Python basic types. (``bool`` instead of ``boolean``) + 2. Use parenthesis for defining shapes: ``array-like of shape (n_samples,)`` + or ``array-like of shape (n_samples, n_features)`` + 3. For strings with multiple options, use brackets: + ``input: {'log', 'squared', 'multinomial'}`` 4. 1D or 2D data can be a subset of - `{array-like, ndarray, sparse matrix, dataframe}`. Note that `array-like` - can also be a `list`, while `ndarray` is explicitly only a `numpy.ndarray`. - An example supporting two of them would be:: - - `{array-like, sparse matrix} shape=(n_samples, n_features)` + ``{array-like, ndarray, sparse matrix, dataframe}``. Note that ``array-like`` + can also be a ``list``, while ``ndarray`` is explicitly only a ``numpy.ndarray``. * For unwritten formatting rules, try to follow existing good works: