cmd docu

TODO.md

@@ -2,4 +2,5 @@
 tags:
 - frrr
 ---
-+ documentation
++ documentation
++ ls colors in config

orvani/cmd.py

@@ -7,29 +7,51 @@ from rich import box
 from rich.console import Console
 from rich.table import Table
 from orvani import OrvaniTag, CONTEXT_FILE, CACHE_FILE, CONTEXTS
-from plugins import frontmatter, hashdoubleslash, id3, office, pdf
 
 def mktable(query: str, index: dict, filter=None, trunc_len: int=25):
+    """Creates a rich table from `otag ls` search result
+    
+    query (str):     The user query
+    index (dict):    The context index returned from `otag ls`
+    filter (bool):   Show only 'files' or 'dirs'
+    trunc_len (int): Max. filename length beyond which overflow method kicks in
+    
+    """
     console = Console()
-    if len(index['found']) > 0:
+
+    if len(index['found']) > 0: # is there a search result?
+
+        # Create table
         table = Table(title=f"Results for `{query}`", box=box.HORIZONTALS, show_lines=True)
-        ctx = list(CONTEXTS.keys())
+
+        # File Path Column Header
         table.add_column("Path", style="white", no_wrap=False, overflow='fold', max_width=40)
+
+        # Create Column Headers based on Context Schema
+        ctx = list(CONTEXTS.keys())
         styles = ["cyan", "yellow", "magenta", "green"]
         for i, c in enumerate(ctx):
             table.add_column(ctx[i].title(), style=styles[i], max_width=12, overflow='fold')
+        
+        # Create Rows Based on Search Results
         for file in index['found']:
             item = Path(file)
-            if filter == 'files' and not item.is_file():
+            
+            if filter == 'files' and not item.is_file(): # Only show directories (--dirs flag)
                 continue
-            if filter == 'dirs' and not item.is_dir():
+            if filter == 'dirs' and not item.is_dir(): # Only show files (--files flag)
                 continue
+
+            # Our own overflow method for filenames longer than 25 characters (file…name.ext)
             long_file_pre = math.floor(trunc_len/2-1)
             long_file_post = len(item.name) - math.ceil(trunc_len/2-1)
             path = f'{item.parent}/' + ((item.name[:long_file_pre] + '…' + item.name[long_file_post:]) if len(item.name) > trunc_len else item.name)
+            
             fc = index['index']['items'][file]
             elements = []
             elements.append(path)
+
+            # Fetch contextual data for each file to add to a table row
             for c in ctx:
                 if not c in fc:
                     fc[c] = None
@@ -38,18 +60,24 @@ def mktable(query: str, index: dict, filter=None, trunc_len: int=25):
                         prefix = CONTEXTS[c]
                     else:
                         prefix = ''
-                    if not type(fc[c]) == str:
+                    if not type(fc[c]) == str: # Add respective context prefix
                         elements.append(' '.join([prefix + tag for tag in fc[c]]))
-                    else:
+                    else: # Except for notes
                         elements.append(fc[c])
                 else:
                     elements.append(None)
+
             table.add_row(*elements)
         console.print(table)
     else:
         console.print(f":thinking_face: [red]No results found for [white]{query}")
 
-def nice_context(context):
+def nice_context(context: dict):
+    """
+    Rich colors for displaying contextual data
+
+    context (dict): context dict
+    """
     string = ''
     if context['projects']:
         string += '[cyan]' + ' '.join(['+' + tag for tag in context['projects']]) + '[/cyan] '
@@ -62,9 +90,12 @@ def nice_context(context):
     return string
 
 def main():
+    """otag CLI"""
 
+    # Rich Console
     console = Console()
 
+    # Detailed Help Text for the --help flag
     command_help = """{add,a} FILE CONTEXT    # add context to an existing file
 {remove,r} FILE CONTEXT # remove context from an existing file
 {list,ls,l} QUERY       # list all files with queried context in current directory tree
@@ -80,7 +111,8 @@ def main():
 {import,i} FILE         # import context for files from a text file
 {export,e} FILE         # export context for files to a text file
 """
-    p = argp(description="OrvaniTagger", formatter_class=raw)
+    # Command Line Argument Setup
+    p = argp(description="OrvaniTagger (otag)", formatter_class=raw)
     p.add_argument("--not-recursive", "-nr", action="store_false",     help="(list,clean,purge,export) Include subdirectories in search")
     p.add_argument("--no-file-operation", "-nf", action="store_false", help="(copy,move,del) Skip file operation, just apply to context")
     p.add_argument("--no-plugins", "-np", action="store_false",        help="(list,export) Don't use plug-ins to search file metadata")
@@ -111,9 +143,11 @@ def main():
     p.print_usage = p.print_help
     args = p.parse_args()
 
+    # Load Orvani
     orvani = OrvaniTag()
     orvani.ENABLE_PLUGINS = args.no_plugins
 
+    # Parse Arguments and Run otag Methods
     try:
         if args.command in ['add', 'a']:
             if args.file and args.context: