|Version 10 (modified by marko, 23 months 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:
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 <../example.py>`.
Delete "uses dataset.tab" 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).
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 = Orange.data.Table("titanic") c = Orange.classification.tree.TreeLearner(data) print c #prints out the model print c.to_string(max_depth=1) #with some special formatting
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 = Orange.data.Table("iris")
In code, use data.