Commits

bworkman  committed 6c90636

add robodoc comments

  • Participants
  • Parent commits eddf607

Comments (0)

Files changed (1)

 MessageBox = ctypes.windll.user32.MessageBoxA
 
 def escape_html(html):
-        """
-        Returns the given HTML with ampersands, quotes and angle brackets encoded.
-        """
+        """****f* dump/escape_html
+        *       DESCRIPTION
+        *               escapes problem characters in unicode strings and returns an ascii encoded representation
+        *       ARGUMENTS
+        *               html -- unicode string to escape
+        *       SIDE EFFECTS
+        *               None.
+        *       RESULT
+        *               ascii encoded escaped string
+        *       SOURCE
+        *"""
         html = unicode(html)
         html = html.replace('&', '&')
         html = html.replace('<', '&lt;')
         html = html.replace("'", '&#39;')
 
         return html.encode('ascii', 'ignore')
+"""*******"""
 
 def slugify(procedureName):
-        """
-        Normalizes string, converts to lowercase, removes non-alpha characters,
-        and converts spaces to hyphens.
-
-        Based on code in: Django
-        """
+        """****f* dump/slugify
+        *       DESCRIPTION
+        *               Normalizes string, converts to lowercase, removes non-alpha characters, and converts spaces to hyphens.
+        *       ARGUMENTS
+        *               procedureName -- string to normalize
+        *       SIDE EFFECTS
+        *               None.
+        *       NOTE
+        *               Based on code in: Django
+        *       RESULT
+        *               normalized string
+        *       SOURCE
+        *"""
         procedureName = unicodedata.normalize('NFKD', unicode(procedureName))
         procedureName = procedureName.encode('ascii', 'ignore')
         procedureName = re.sub('[^\w\s-]', '', procedureName).strip().lower()
         procedureName = re.sub('[-\s]+', '-', procedureName)
         return procedureName
+"""*******"""
 
 def get_dir() :
-
+        """****f* dump/get_dir
+        *       DESCRIPTION
+        *               prompts the user with a directory selection dialog
+        *       ARGUMENTS
+        *               None.
+        *       SIDE EFFECTS
+        *               None.
+        *       NOTE
+        *               requires PyGtk 2.3.90 or later
+        *       RESULT
+        *               path of the directory selected
+        *       SOURCE
+        *"""
         response = ""
 
         # Check for new pygtk: this is new class in PyGtk 2.4
         dialog.destroy()
 
         return response
+"""*******"""
 
 def variable_type(t) :
+        """****f* dump/variable_type
+        *       DESCRIPTION
+        *               returns a string representation of a python-fu variable type
+        *       ARGUMENTS
+        *               t -- python-fu type to check
+        *       SIDE EFFECTS
+        *               None.
+        *       NOTE
+        *               type "PF_REGION" is in the python-fu documentation, but not defined at run-time
+        *       RESULT
+        *               "unknown" -- if the type could not be found
+        *               string representation otherwise
+        *       SOURCE
+        *"""
 
-
-        """
-        in the documentation, but not defined in gimpfu
-        PF_REGION:"PF_REGION"
-        """
         types = {PF_INT8:"PF_INT8",PF_INT16:"PF_INT16",PF_INT32:"PF_INT32",PF_INT:"PF_INT",PF_FLOAT:"PF_FLOAT",PF_STRING:"PF_STRING",PF_VALUE:"PF_VALUE",PF_COLOR:"PF_COLOR",PF_COLOUR:"PF_COLOUR",PF_IMAGE:"PF_IMAGE",PF_LAYER:"PF_LAYER",PF_CHANNEL:"PF_CHANNEL",PF_DRAWABLE:"PF_DRAWABLE",PF_TOGGLE:"PF_TOGGLE",PF_BOOL:"PF_BOOL",PF_RADIO:"PF_RADIO",PF_SLIDER:"PF_SLIDER",PF_SPINNER:"PF_SPINNER",PF_ADJUSTMENT:"PF_ADJUSTMENT",PF_FONT:"PF_FONT",PF_FILE:"PF_FILE",PF_BRUSH:"PF_BRUSH",PF_PATTERN:"PF_PATTERN",PF_GRADIENT:"PF_GRADIENT",PF_PALETTE:"PF_PALETTE"}
 
         if (t not in types) :
                 return "unknown"
 
         return types[t]
+"""*******"""
 
 def procedure_type(t) :
+        """****f* dump/procedure_type
+        *       DESCRIPTION
+        *               returns a string representation of a python-fu procedure type
+        *       ARGUMENTS
+        *               t -- python-fu type to check
+        *       SIDE EFFECTS
+        *               None.
+        *       RESULT
+        *               "unknown" -- if the type could not be found
+        *               string representation otherwise
+        *       SOURCE
+        *"""
 
         types = {PLUGIN:"PROC_PLUG_IN",EXTENSION:"PROC_EXTENSION",TEMPORARY:"PROC_TEMPORARY"}
 
                 return "unknown"
 
         return types[t]
+"""*******"""
 
 def alt_table(variables) :
+        """****f* dump/alt_table
+        *       DESCRIPTION
+        *               returns an HTML table containing the list of variables in a string
+        *       ARGUMENTS
+        *               variables -- list of python-fu variables to format
+        *       SIDE EFFECTS
+        *               None.
+        *       NOTE
+        *               table contains alternating colored rows
+        *       RESULT
+        *               string containing HTML table
+        *       SOURCE
+        *"""
 
         if(0 == len(variables)):
                 return "<p>None</p>"
                 alt = not alt
 
         return Template(table).safe_substitute({"body":html, "offset":"\t\t"})
+"""*******"""
 
 def index_table(links, maxRowLen=5):
+        """****f* dump/index_table
+        *       DESCRIPTION
+        *               returns an html table containing the list of links in a string
+        *       ARGUMENTS
+        *               links           -- list of link objects (dictionary containing keys [href, name])
+        *               maxRowLen       -- maximum number of links to display per a table row
+        *       SIDE EFFECTS
+        *               None.
+        *       RESULT
+        *               string containing HTML table
+        *       SOURCE
+        *"""
 
         if(0 == len(links)):
                 return ""
         buf += '\t\t\t</tr>\n\t\t</table>'
 
         return buf
+"""*******"""
 
 def insert(root, path):
-
+        """****f* dump/insert
+        *       DESCRIPTION
+        *               inserts a path into a tree 
+        *       ARGUMENTS
+        *               root    -- root node (touple:string,list) to use when inserting
+        *               path    -- list of strings to insert
+        *       SIDE EFFECTS
+        *               inserts path into tree starting at root
+        *       RESULT
+        *               None.
+        *       SOURCE
+        *"""
         for part in path:
                 ptr = None
                 for tup in root[1]:
                         root[1].sort(key=lambda tup: tup[0])
 
                 root = ptr
+"""*******"""
 
 def size(root):
-
+        """****f* dump/size
+        *       DESCRIPTION
+        *               returns the number of nodes in a tree
+        *       ARGUMENTS
+        *               root    -- root node (touple:string,list) to start counting from
+        *       SIDE EFFECTS
+        *               None.
+        *       RESULT
+        *               the number of nodes in the tree
+        *       SOURCE
+        *"""
         children = 0
         unvisited = deque()
         unvisited.append(root)
                         unvisited.append(tup)
 
         return children
+"""*******"""
 
 def namespaces(root, delimiter="-", minSize=10):
-
+        """****f* dump/namespaces
+        *       DESCRIPTION
+        *               returns the list of namespaces from the given tree
+        *       ARGUMENTS
+        *               root            -- root node (touple:string,list) to generate namespaces from
+        *               delimiter       -- the delimiter to join the namespace elements with
+        *               minSize         -- the minimum number of items that must reside in the namespace before returning it
+        *       SIDE EFFECTS
+        *               None.
+        *       NOTE
+        *               if a direct child of root node doesnt contain minSize children, it is returned anyway
+        *       RESULT
+        *               list of namespaces (strings joined on delimiter) contained in root
+        *       SOURCE
+        *"""
         ns_list = list()
         unvisited = list()
         visited = dict()
                         unvisited.pop()
 
         return ns_list
+"""*******"""
 
 def make_heading_filter(procedureNames):
-
+        """****f* dump/make_heading_filter
+        *       DESCRIPTION
+        *               closure for headings filter
+        *       ARGUMENTS
+        *               procedureNames -- list of procedure names to filter headings for
+        *       SIDE EFFECTS
+        *               None.
+        *       RESULT
+        *               filter function for headings
+        *       SOURCE
+        *"""
         procedureNames = list(procedureNames)
 
         def filter_headings(ns):
                 return True
 
         return filter_headings
+"""*******"""
 
 def headings(procedureNames, delimiter="-", minSize=7):
-
+        """****f* dump/headings
+        *       DESCRIPTION
+        *               return a list of headings for procedure name index
+        *       ARGUMENTS
+        *               procedureNames  -- list of procedure names to generate headings for
+        *               delimiter       -- character that separates spaces in procedureNames
+        *               minSize         -- minimum number of procedures that should be under a namespace before making it a heading
+        *       SIDE EFFECTS
+        *               None.
+        *       RESULT
+        *               list of headings to use in index
+        *       SOURCE
+        *"""
         root = ("root", list())
 
         for pname in procedureNames:
                 heading_list.extend(namespaces(node, delimiter, minSize))
 
         return filter(make_heading_filter(procedureNames),heading_list)
-
+"""*******"""
 
 
 def transform(procedure) :
-
+        """****f* dump/transform
+        *       DESCRIPTION
+        *               maps a python-fu procedure object to dictionary
+        *       ARGUMENTS
+        *               procedure -- the python-fu procedure object to transform
+        *       SIDE EFFECTS
+        *               None.
+        *       RESULT
+        *               dictionary containing mapped attributes
+        *       SOURCE
+        *"""
         dct = dict()
 
         dct["name"] = escape_html(procedure.proc_name)
         dct["results"] = alt_table(procedure.return_vals)
 
         return dct
+"""*******"""
 
 def procedure_body(procedure):
+        """****f* dump/procedure_body
+        *       DESCRIPTION
+        *               returns an HTML representation of a python-fu procedure object in a string
+        *       ARGUMENTS
+        *               procedure -- the python-fu procedure object to format
+        *       SIDE EFFECTS
+        *               None.
+        *       RESULT
+        *               HTML string containing procedure attributes
+        *       SOURCE
+        *"""
         return Template("""
                 <hr style="margin-bottom:0px;"/>
                 <div style="display:inline-block;">
                 <h4>Return</h4>
                 ${results}
                 <hr style="margin-bottom:0px;" />""").safe_substitute(transform(procedure))
+"""*******"""
 
 def make_linker(base="",ext=".html") :
+        """****f* dump/make_linker
+        *       DESCRIPTION
+        *               closure for procedure name to HTML anchor
+        *       ARGUMENTS
+        *               base    -- a base for the anchor href
+        *               ext     -- tail for the anchor href
+        *       SIDE EFFECTS
+        *               None.
+        *       RESULT
+        *               function to construct anchors
+        *       SOURCE
+        *"""
         def linker(pname):
                 return {"name":pname,"href":"%s%s%s"%(base, slugify(pname), ext)}
         return linker
+"""*******"""
 
 def dump_pdb(minSize, singleFile) :
-
+        """****f* dump/dump_pdb
+        *       DESCRIPTION
+        *               python-fu function, outputs procedural database to HTML
+        *       ARGUMENTS
+        *               minSize         -- minimum number of children in a namespace before giving it a separate index table
+        *               singleFile      -- boolean value, if true output entire procedural database and index into one file
+        *       SIDE EFFECTS
+        *               writes HTML files containing procedural database to directory chosen user
+        *               if single file -- writes "index.html" out to chosen directory
+        *               else -- writes "index.html", "main.css" out to chosen directory, and one html file per function to <directory>/pdb/
+        *       NOTE
+        *               headings are determined dynamically at run-time by breaking the procedural database into namespaces and taking those namespaces which have a minimum number of elements
+        *               headings are mapped alphabetically, depth-first, to ensure proper output
+        *       RESULT
+        *               None.
+        *****"""
         root = get_dir()
         if("" == root) :
                 return None
                 f.write(Template(__INDEX_HTML).safe_substitute({"date":now,"body":index_buf + proc_buf, "css":css}))
 
         return None
+"""*******"""
 
+"""****h* dump/dump
+*       DESCRIPTION
+*               Python-fu plug-in that outputs the gimp procedural database in formatted HTML and CSS
+*       ARGUMENTS
+*               None.
+*       SIDE EFFECTS
+*               Adds to GIMP menu "Help", item "Procedure Dump"
+*       RESULT
+*               None.
+*       NOTE
+*               provides two configurable options:
+*               single file - output is dumped into one file "index.html" in selected directory
+*               scale - the minimum number of sub items a namespace must contain to be broken up into its own index (very large number => very few index tables)
+*       SOURCE
+*"""
 register(
         #name
         "dump-pdb",
 )
 
 main()
+"""*******"""