Fix doc and improve arguments readability

command_line/cadbiom_cmd/cadbiom_cmd.py

@@ -47,14 +47,14 @@ def launch_researchs(args):
 
 
 def launch_sort(args):
-    """Parse a solution file or a directory of solution files,
-    and sort all frontier places/boundaries in alphabetical order.
+    """Read a solution file or a directory containing solution files
+    (*cam* files), and sort all frontier places/boundaries in alphabetical order.
     """
 
     # Module import
     import solution_sort
     params = args_to_param(args)
-    solution_sort.sort_solutions(params['sol_file'])
+    solution_sort.sort_solutions(params['path'])
 
 
 def traj_2_graph(args):
@@ -260,7 +260,7 @@ def main():
     # Solution file (complete or not)
     parser_solutions_sort = subparsers.add_parser('sort_solutions',
                                                   help=launch_sort.__doc__)
-    parser_solutions_sort.add_argument('sol_file',
+    parser_solutions_sort.add_argument('path',
         help="Solution file or directory with solution files " + \
         "(output of 'compute_macs' command).")
     parser_solutions_sort.set_defaults(func=launch_sort)

command_line/cadbiom_cmd/solution_sort.py

@@ -31,17 +31,30 @@ import os
 import glob
 
 
-## Handle output files #########################################################
+## Handle *cam* files ##########################################################
 
 def get_solutions(file_descriptor):
     """Generator of solution lines and corresponding stripped lines.
 
-    .. note:: Do not return events ! Just sets of frontier places.
+    .. note:: This function do not return events! It is just original lines and
+        cleaned lines containing solutions (i.e sets of frontier
+        places/boundaries).
+
+        We remove the last ``'\\n'`` and ``'\\t'``.
+        Tabs in the middle are replaced by one space ``' '``.
 
     :param: Opened file.
     :type: <file>
-    :return: Line (without ``'\\n'``) and stripped line (with ``'\\'``
-        replaced by ``' '`` (except for final ``'\\t'``)).
+    :return: A generator of tuples; each tuple contains the original line,
+        and the cleaned line.
+
+        :Example:
+
+            For an original line: ``'Z\tY\X'``
+
+            .. code-block:: python
+                ('Z\tY\X', 'X Y Z')
+
     :rtype: <tuple <str>, <str>>
     """
 
@@ -73,37 +86,39 @@ def sort_solutions_in_file(filepath):
 
     solutions = dict()
 
-    with open(filepath, 'r+') as fd:
+    with open(filepath, 'r+') as f_d:
 
         # Get old line as key and ordered line as value
-        for line, stripped_line in get_solutions(fd):
+        for line, stripped_line in get_solutions(f_d):
             # Sort in lower case, remove ' ' empty elements
             solutions[line] = \
                 " ".join(sorted([place for place in stripped_line.split(' ')
                                  if place != ' '], key=lambda s: s.lower()))
 
         # Rewind the whole file
-        fd.seek(0)
+        f_d.seek(0)
 
         # Load all the content
-        file_text = fd.read()
+        file_text = f_d.read()
 
         # Replace old sols with the new ones
         for original_sol, sorted_sol in solutions.items():
             file_text = file_text.replace(original_sol, sorted_sol)
 
         # Rewind the whole file
-        fd.seek(0)
+        f_d.seek(0)
 
         # Write all text in the current opened file
-        fd.write(file_text)
+        f_d.write(file_text)
 
 
 def sort_solutions(path):
     """Entry point for sorting solutions.
 
-    Read a solution file and sort in place,
-    all frontier places in alphabetical order.
+    Read a solution(s) file(s) (*cam* files) and sort all
+    frontier places/boundaries in alphabetical order.
+
+    .. warning:: The files will be modified in place.
 
     :param: Filepath or directory path containing Cadbiom solutions.
     :type: <str>