Merge pull request #3505 from ajdapretnar/docs-to-md

[DOC] Transform documentation to .md

Author: janezd

appveyor.yml

@@ -18,7 +18,7 @@ environment:
     # disable threaded builds on Python 3.5+ when using numpy's distutils
     # (https://github.com/numpy/numpy/issues/7607)
     BUILD_GLOBAL_OPTIONS: build -j1
-    BUILD_ENV: wheel==0.29.0 pip==9.0.1 numpy==1.9.3 sphinx==1.8.2
+    BUILD_ENV: wheel==0.29.0 pip==9.0.1 numpy==1.9.3 -r requirements-doc.txt
     # SIP 4.19.4+ with PyQt5==5.9.1+ segfault our tests (GH-2756)
     TEST_ENV: sip==4.19.6 PyQt5==5.9.2 numpy~=1.14.0 scipy~=1.0.0 scikit-learn pandas==0.21.1
 

doc/visual-programming/source/conf.py

@@ -15,7 +15,7 @@
 
 import sys
 import os
-import shlex
+from recommonmark.parser import CommonMarkParser
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -39,15 +39,17 @@
     'sphinx.ext.todo',
     'sphinx.ext.imgmath',
     'sphinx.ext.ifconfig',
-    'sphinx.ext.viewcode',
+    'sphinx.ext.viewcode'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
+source_parsers = {'.md': CommonMarkParser}
+
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
-source_suffix = ['.rst']
+source_suffix = ['.md', '.rst']
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
@@ -214,7 +216,7 @@
 
 # -- Options for LaTeX output ---------------------------------------------
 
-latex_elements = {
+# latex_elements = {
 # The paper size ('letterpaper' or 'a4paper').
 #'papersize': 'letterpaper',
 
@@ -226,14 +228,15 @@
 
 # Latex figure (float) alignment
 #'figure_align': 'htbp',
-}
+# }
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-  (master_doc, 'OrangeVisualProgramming.tex', 'Orange Visual Programming Documentation',
-   'Orange Data Mining', 'manual'),
+    (master_doc, 'OrangeVisualProgramming.tex',
+     'Orange Visual Programming Documentation',
+     'Orange Data Mining', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -262,7 +265,8 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'orangevisualprogramming', 'Orange Visual Programming Documentation',
+    (master_doc, 'orangevisualprogramming',
+     'Orange Visual Programming Documentation',
      [author], 1)
 ]
 
@@ -276,9 +280,10 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  (master_doc, 'OrangeVisualProgramming', 'Orange Visual Programming Documentation',
-   author, 'OrangeVisualProgramming', 'One line description of project.',
-   'Miscellaneous'),
+    (master_doc, 'OrangeVisualProgramming',
+     'Orange Visual Programming Documentation', author,
+     'OrangeVisualProgramming', 'One line description of project.',
+     'Miscellaneous'),
 ]
 
 # Documents to append as an appendix to all manuals.
@@ -366,7 +371,3 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'https://docs.python.org/': None}
-
-
-def setup(app):
-    app.add_stylesheet('style.css')

…rogramming/source/widgets/data/color.rst …programming/source/widgets/data/color.mddoc/visual-programming/source/widgets/data/color.rst renamed to doc/visual-programming/source/widgets/data/color.md doc/visual-programming/source/widgets/data/color.rst renamed to doc/visual-programming/source/widgets/data/color.md

@@ -1,65 +1,59 @@
 Color
 =====
 
-Set color legend for variables. 
+Set color legend for variables.
 
-Inputs
-    Data
-        input dataset
+**Inputs**
 
-Outputs
-    Data
-        dataset with a new color legend
+- Data: input data set
 
+**Outputs**
 
-The **Color** widget enables you to set the color legend in your visualizations 
-according to your own preferences. This option provides you with the tools for 
-emphasizing your results and offers a great variety of color options for presenting your data. It can be combined with most visualizations widgets. 
+- Data: data set with a new color legend
 
-.. figure:: images/Color-stamped.png
+The **Color** widget enables you to set the color legend in your visualizations according to your own preferences. This option provides you with the tools for emphasizing your results and offers a great variety of color options for presenting your data. It can be combined with most visualizations widgets.
 
-1. A list of discrete variables. You can set the color of each variable by double-clicking on it and opening the *Color palette* or the *Select color* window. The widget also enables text-editing. By clicking on a variable, you can change its name. 
-2. A list of continuous variables. You can customize the color gradients by double-clicking on them. The widget also enables text-editing. By clicking on a variable, you can change its name. If you hover over the right side side of the gradient, *Copy to all* appears. You can then apply your customized color gradient to all variables. 
+![](images/Color-stamped.png)
+
+1. A list of discrete variables. You can set the color of each variable by double-clicking on it and opening the *Color palette* or the *Select color* window. The widget also enables text-editing. By clicking on a variable, you can change its name.
+2. A list of continuous variables. You can customize the color gradients by double-clicking on them. The widget also enables text-editing. By clicking on a variable, you can change its name. If you hover over the right side side of the gradient, *Copy to all* appears. You can then apply your customized color gradient to all variables.
 3. Produce a report.
-4. Apply changes. If *Apply automatically* is ticked, changes will be communicated automatically. Alternatively, just click *Apply*. 
+4. Apply changes. If *Apply automatically* is ticked, changes will be communicated automatically. Alternatively, just click *Apply*.
 
 Discrete variables
 ------------------
 
-.. figure:: images/Color-palette-discrete-stamped.png
+![](images/Color-palette-discrete-stamped.png)
 
-1. Choose a desired color from the palette of basic colors. 
-2. Move the cursor to choose a custom color from the color palette. 
+1. Choose a desired color from the palette of basic colors.
+2. Move the cursor to choose a custom color from the color palette.
 3. Choose a custom color from your previously saved color choices.
 4. Specify the custom color by:
-
-  -  entering the red, green, and blue components of the color as values between 0 (darkest) and 255 (brightest)
-  -  entering the hue, saturation and luminescence components of the color as values in the range 0 to 255
-
+    - entering the red, green, and blue components of the color as values between 0 (darkest) and 255 (brightest)
+    - entering the hue, saturation and luminescence components of the color as values in the range 0 to 255
 5. Add the created color to your custom colors.
-6. Click *OK* to save your choices or *Cancel* to exit the the color palette. 
+6. Click *OK* to save your choices or *Cancel* to exit the the color palette.
 
 Numeric variables
 -----------------
 
-.. figure:: images/Color-palette-numeric-stamped.png
+![](images/Color-palette-numeric-stamped.png)
 
-1. Choose a gradient from your saved profiles. The default profile is already set. 
+1. Choose a gradient from your saved profiles. The default profile is already set.
 2. The gradient palette
-3. Select the left side of the gradient. Double clicking the color opens the *Select Color* window. 
-4. Select the right side of the gradient. Double clicking the color opens the *Select Color* window. 
+3. Select the left side of the gradient. Double clicking the color opens the *Select Color* window.
+4. Select the right side of the gradient. Double clicking the color opens the *Select Color* window.
 5. Pass through black.
-6. Click *OK* to save your choices or *Cancel* to exit the color palette. 
+6. Click *OK* to save your choices or *Cancel* to exit the color palette.
 
 Example
 -------
 
-We chose to work with the *Iris* dataset. We opened the color palette and selected three new colors for the three types of Irises. Then we opened the :doc:`Scatter Plot<../visualize/scatterplot>` widget and viewed the changes made to the scatter plot. 
-
-.. figure:: images/Color-Example-1.png
+We chose to work with the *Iris* data set. We opened the color palette and selected three new colors for the three types of Irises. Then we opened the [Scatter Plot](../visualize/scatterplot.md) widget and viewed the changes made to the scatter plot.
 
-For our second example, we wished to demonstrate the use of the **Color** widget with continuous variables. We put different types of Irises on the x axis and petal length on the y axis. We created a new color gradient and named it greed (green + red). 
-In order to show that sepal length is not a deciding factor in differentiating between different types of Irises, we chose to color the points according to sepal width. 
+![](images/Color-Example-1.png)
 
+For our second example, we wished to demonstrate the use of the **Color** widget with continuous variables. We put different types of Irises on the x axis and petal length on the y axis. We created a new color gradient and named it greed (green + red).
+In order to show that sepal length is not a deciding factor in differentiating between different types of Irises, we chose to color the points according to sepal width.
 
-.. figure:: images/Color-Example-2.png
+![](images/Color-Example-2.png)

doc/visual-programming/source/widgets/data/concatenate.md

@@ -0,0 +1,33 @@
+Concatenate
+===========
+
+Concatenates data from multiple sources.
+
+**Inputs**
+
+- Primary Data: data set that defines the attribute set
+- Additional Data: additional data set
+
+**Outputs**
+
+- Data: concatenated data
+
+The widget concatenates multiple sets of instances (data sets). The merge is “vertical”, in a sense that two sets of 10 and 5 instances yield a new set of 15 instances.
+
+![](images/Concatenate-stamped.png)
+
+1. Set the attribute merging method.
+2. Add the identification of source data sets to the output data set.
+3. Produce a report.
+4. If *Apply automatically* is ticked, changes are communicated automatically. Otherwise, click *Apply*.
+
+If one of the tables is connected to the widget as the primary table, the resulting table will contain its own attributes. If there is no primary table, the attributes can be either a union of all attributes that appear in the tables specified as *Additional Tables*, or their intersection, that is, a list of attributes common to all the connected tables.
+
+Example
+-------
+
+As shown below, the widget can be used for merging data from two separate files. Let's say we have two data sets with the same attributes, one containing instances from the first experiment and the other instances from the second experiment and we wish to join the two data tables together. We use the **Concatenate** widget to merge the data sets by attributes (appending new rows under existing attributes).
+
+Below, we used a modified *Zoo* data set. In the [first](http://file.biolab.si/datasets/zoo-first.tab) [File](../data/file.md) widget, we loaded only the animals beginning with the letters A and B and in the [second](http://file.biolab.si/datasets/zoo-second.tab) one only the animals beginning with the letter C. Upon concatenation, we observe the new data in the [Data Table](../data/datatable.md) widget, where we see the complete table with animals from A to C.
+
+![](images/Concatenate-Example.png)

doc/visual-programming/source/widgets/data/concatenate.rst

@@ -0,0 +1,42 @@
+Continuize
+==========
+
+Turns discrete attributes into continuous dummy variables.
+
+**Inputs**
+
+- Data: input data set
+
+**Outputs**
+
+- Data: data set with continuized instances
+
+The **Continuize** widget receives a data set in the input and outputs the same data set in which the discrete attributes (including binary attributes) are replaced with continuous ones.
+
+![](images/Continuize-stamped.png)
+
+1. [Continuization methods](https://en.wikipedia.org/wiki/Continuity_correction), which define the treatment of multivalued discrete attributes. Say that we have a discrete attribute status with the values low, middle and high, listed in that order. Options for their transformation are:  
+
+   - **Target or First value as base**: the attribute will be transformed into two continuous attributes, status=middle with values 0 or 1 signifying whether the original attribute had value middle on a particular example, and similarly, status=high. Hence, a three-valued attribute is transformed into two continuous attributes, corresponding to all except the first value of the attribute.
+   - **Most frequent value as base**: similar to the above, except that the data is analyzed and the most frequent value is used as a base. So, if most examples have the value middle, the two newly constructed continuous attributes will be status=low and status=high.
+   - **One attribute per value**: this would construct three continuous attributes out of a three-valued discrete one.
+   - **Ignore multinominal attributes**: removes the multinominal attributes from the data.
+   - **Treat as ordinal**: converts the attribute into a continuous attribute with values 0, 1, and 2.
+   - **Divide by number of values**: same as above, except that the values are normalized into range 0-1. So, our case would give values 0, 0.5 and 1.
+
+2. Define the treatment of continuous attributes. You will usually prefer the *Leave them as they are* option. The alternative is *Normalize by span*, which will subtract the lowest value found in the data and divide by the span, so all values will fit into [0, 1]. Finally,*Normalize by standard deviation* subtracts the average and divides by the deviation.
+3. Define the treatment of class attributes. Besides leaving it as it is, there are also a couple of options available for multinominal attributes, except for those options which split the attribute into more than one attribute - this obviously cannot be supported since you cannot have more than one class attribute.
+4. With *value range*, you can define the values of new attributes. In the above text, we supposed the range *from 0 to 1*. You can change it to *from -1 to 1*.
+5. Produce a report.
+6. If *Apply automatically* is ticked, changes are committed automatically. Otherwise, you have to press *Apply* after each change.
+
+Examples
+--------
+
+First, let's see what is the output of the **Continuize** widget. We feed the original data (the *Heart disease* data set) into the [Data Table](../data/datatable) and see how they look like. Then we continuize the discrete values and observe them in another [Data Table](../data/datatable).
+
+![](images/Continuize-Example1.png)
+
+In the second example, we show a typical use of this widget - in order to properly plot the linear projection of the data, discrete attributes need to be converted to continuous ones and that is why we put the data through the **Continuize** widget before drawing it. The attribute "*chest pain*" originally had four values and was transformed into three continuous attributes; similar happened to gender, which was transformed into a single attribute "*gender=female*".
+
+![](images/Continuize-Example2.png)