Version 11 (modified by marko, 3 years ago) (diff)



Avoid conversational style that was common in previous documentation (for example, rewrite sentences containing "you"). Avoid future tense; use present instead (for example, "classifier will be used" -> classifier is used").

Examples of documentation that is OK:

Documentation checking stories: #882, #933, #939, #966, #986.

Code samples

Each code sample should be a python script and should only be (perhaps partially) referenced in the file. Never copy the code into the documentation. This also holds for most of the one-liners, as code in separate files is much easier to test and fix when interface changes.

Import just Orange and use full paths. Avoid exceptions. Never import *.

Use download to link downloadable files, for example

See :download:`this example script <../>`.

Delete "uses" from introductions to examples, because data sets from the documentation can now be loaded easily. Decide whether the .py file needs to be linked yourself.

Referencing other classes, functions, methods

If it is clear what are writing about, use shorter form, for example, :obj:`~Orange.classification.rules.X` instead of :obj:`Orange.classification.rules.X`.


CamelCase to underscore_separated

Names of methods, functions, (object) attributes and keyword attributes of functions should all be underscore_separated. Abbreviations should also be in lower case. For example, we should rename AUCWilcoxon to auc_wilcoxon (and not AUC_wilcoxon).

For now, all C++ code is accessible both with CamelCase and underscore separated (detailed description). Python code should be converted with name deprecation decorators (see the page for an example).

Refactoring tool

Do forget to update the refactoring rules.

Output of models

Output of learning models. Learning models (classifiers, regressors) need to have __str__ defined. If it needs a parameter, also add a to_string method, but __str__ should still return something. For example

data ="titanic")
c = Orange.classification.tree.TreeLearner(data)
print c #prints out the model
print c.to_string(max_depth=1) #with some special formatting

Model plotting

The most typical one should be plot(), but if there are multiple different plots, prefix them with plot_, for example plot_dendrogram.

Data set naming

In documentation, do not use table. Name of the data set is preferred (but just data is also acceptable), so write:

iris ="iris")

In code, use data.