add documentation

Author: giannisdoukas

docs/index.rst

@@ -30,18 +30,53 @@ IPython2CWL is a tool for converting `IPython <https://ipython.org/>`_ Jupyter N
 ------------------------------------------------------------------------------------------
 
 IPython2CWL is based on `repo2docker <https://github.com/jupyter/repo2docker>`_, the same tool
-used by `mybinder <https://mybinder.org/>`_. Now, by writing Jupyter Notebook and publish them, including repo2docker
-configuration, the community can not only execute the notebooks remotely but also to use them as steps in scientific
+used by `mybinder <https://mybinder.org/>`_. Now, by writing Jupyter Notebook and publishing them, including repo2docker
+configuration, the community can not only execute the notebooks remotely but can also use them as steps in scientific
 workflows.
 
-* Install ipython2cwl: :code:`pip install python2cwl`
+* `Install ipython2cwl <https://pypi.org/project/ipython2cwl/>`_: :code:`pip install ipython2cwl`
 * Ensure that you have docker running
 * Create a directory to store the generated cwl files, for example cwlbuild
 * Execute :code:`jupyter repo2cwl https://github.com/giannisdoukas/cwl-annotated-jupyter-notebook.git -o cwlbuild`
 
-Indices and tables
-==================
+HOW IT WORKS?
+------------------
+
+IPython2CWL parses each IPython notebook and finds the variables with the typing annotations. For each input variable,
+the assigment of that variable will be generalised as a command line argument. Each output variable will be mapped
+in the cwl description as an output file.
+
+SUPPORTED TYPES
+------------------
+
+.. automodule:: ipython2cwl.iotypes
+   :members:
+
+
+THAT'S COOL! WHAT ABOUT LIST & OPTIONAL ARGUMENTS?
+"""""""""""""""""""""""""""""""""""""""""""""""""""
+
+The basic input data types can be combined with the List and Optional annotations. For example, write the following
+annotation:
+
+.. code-block:: python
+
+  file_inputs: List[CWLFilePathInput] = ['data1.txt', 'data2.txt', 'data3.txt']
+  example: Optional[CWLStringInput] = None
+
+
+SEEMS INTERESTING! WHAT ABOUT A DEMO?
+----------------------------------------
+
+If you would like to see a demo before you want to start annotating your notebooks check here!
+`github.com/giannisdoukas/ipython2cwl-demo <https://github.com/giannisdoukas/ipython2cwl-demo>`_
+
+
+WHAT IF I WANT TO VALIDATE THAT THE GENERATED SCRIPTS ARE CORRECT?
+------------------------------------------------------------------
+
+All the generated scripts are stored in the docker image under the directory :code:`/app/cwl/bin`. You can see the list
+of the files by running :code:`docker run [IMAGE_ID] find /app/cwl/bin/ -type f`.
+
+
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`

ipython2cwl/iotypes.py

@@ -1,3 +1,37 @@
+"""
+
+Basic Data Types
+^^^^^^^^^^^^^^^^^
+
+Each variable can be an input or an output. The basic data types are:
+
+* Inputs:
+
+  * CWLFilePathInput
+
+  * CWLBooleanInput
+
+  * CWLStringInput
+
+  * CWLIntInput
+
+* Outputs:
+
+  * CWLFilePathOutput
+
+  * CWLDumpableFile
+
+  * CWLDumpableBinaryFile
+
+
+Complex Dumpables Types
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Dumpables are variables which are able to be written to a file, but the jupyter notebook developer
+does not want to write it, for example to avoid the IO overhead. To bypass that, you can use
+Dumpables annotation. See :func:`~iotypes.CWLDumpable.dump` for more details.
+
+"""
 from typing import Callable
 
 
@@ -6,18 +40,50 @@ class _CWLInput:
 
 
 class CWLFilePathInput(str, _CWLInput):
+    """Use that hint to annotate that a variable is a string-path input. You can use the typing annotation
+    as a string by importing it. At the generated script a command line argument with the name of the variable
+    will be created and the assignment of value will be generalised.
+
+    >>> dataset1: CWLFilePathInput = './data/data.csv'
+    >>> dataset2: 'CWLFilePathInput' = './data/data.csv'
+
+    """
     pass
 
 
 class CWLBooleanInput(_CWLInput):
+    """Use that hint to annotate that a variable is a boolean input. You can use the typing annotation
+    as a string by importing it. At the generated script a command line argument with the name of the variable
+    will be created and the assignment of value will be generalised.
+
+    >>> dataset1: CWLBooleanInput = True
+    >>> dataset2: 'CWLBooleanInput' = False
+
+    """
     pass
 
 
 class CWLStringInput(str, _CWLInput):
+    """Use that hint to annotate that a variable is a string input. You can use the typing annotation
+        as a string by importing it. At the generated script a command line argument with the name of the variable
+        will be created and the assignment of value will be generalised.
+
+        >>> dataset1: CWLBooleanInput = 'this is a message input'
+        >>> dataset2: 'CWLBooleanInput' = 'yet another message input'
+
+        """
     pass
 
 
 class CWLIntInput(_CWLInput):
+    """Use that hint to annotate that a variable is a integer input. You can use the typing annotation
+    as a string by importing it. At the generated script a command line argument with the name of the variable
+    will be created and the assignment of value will be generalised.
+
+    >>> dataset1: CWLBooleanInput = 1
+    >>> dataset2: 'CWLBooleanInput' = 2
+
+    """
     pass
 
 
@@ -26,19 +92,69 @@ class _CWLOutput:
 
 
 class CWLFilePathOutput(str, _CWLOutput):
+    """Use that hint to annotate that a variable is a string-path to an output file. You can use the typing annotation
+    as a string by importing it. The generated file will be mapped as a CWL output.
+
+    >>> filename: CWLBooleanInput = 'data.csv'
+
+    """
     pass
 
 
 class CWLDumpable(_CWLOutput):
+    """Use that class to define custom Dumpables variables."""
 
     @classmethod
-    def dump(cls, dumper: Callable, *args, **kwargs):
+    def dump(cls, dumper: Callable, filename, *args, **kwargs):
+        """
+        Set the function to be used to dump the variable to a file.
+
+        >>> import pandas
+        >>> d: CWLDumpable.dump(d.to_csv, "dumpable.csv", sep="\\t", index=False) = pandas.DataFrame(
+        ...     [[1,2,3], [4,5,6], [7,8,9]]
+        ... )
+
+        In that example the converter will add at the end of the script the following line:
+        >>> d.to_csv("dumpable.csv", sep="\\t", index=False)
+
+        :param dumper: The function that has to be called to write the variable to a file.
+        :param filename: The name of the generated file. That string must be the first argument
+                        in the dumper function. That file will also be mapped as an output in
+                        the CWL file.
+        :param args: Any positional arguments you want to pass to dumper after the filename
+        :param kwargs: Any keyword arguments you want to pass to dumper
+        """
         return _CWLOutput
 
 
 class CWLDumpableFile(CWLDumpable):
+    """Use that annotation to define that a variable should be dumped to a text file. For example for the annotation:
+
+    >>> data: CWLDumpableFile = "this is text data"
+
+
+    the converter will append at the end of the script the following lines:
+
+
+    >>> with open('data', 'w') as f:
+    ...     f.write(data)
+
+
+    and at the CWL, the data, will be mapped as a output.
+    """
     pass
 
 
 class CWLDumpableBinaryFile(CWLDumpable):
+    """Use that annotation to define that a variable should be dumped to a binary file. For example for the annotation:
+
+    >>> data: CWLDumpableBinaryFile = b"this is text data"
+
+    the converter will append at the end of the script the following lines:
+
+    >>> with open('data', 'wb') as f:
+    ...     f.write(data)
+
+    and at the CWL, the data, will be mapped as a output.
+    """
     pass