Merge pull request #149 from erik-whiting/add-documentation-pre-GSOC-…

…2022

Add documentation pre-GSOC 2022

CONTRIBUTING.md

@@ -0,0 +1,39 @@
+Help us to make autowrap better and become part of the OpenMS open-source community.
+
+This document is displayed because you either opened an issue or you want to provide your code as a pull request for inclusion into autowrap. Please take a look at the appropriate section below to find some details on how we handle this process.
+When interacting with other developers, users or anyone else from our community, please adhere to
+[the OpenMS CODE OF CONDUCT](https://github.com/OpenMS/OpenMS/blob/develop/CODE_OF_CONDUCT.md)
+
+# Reporting an Issue:
+
+You most likely came here to:
+  - report bugs or annoyances
+  - pose questions
+  - point out missing documentation
+  - request new features
+
+If you found a bug, e.g. an autowrap tool crashes during code generation, it is essential to provide some basic information:
+  - the autowrap version you are running
+  - the platform you are running autowrap on (Windows 10, ...)
+  - how you installed autowrap (e.g., from source, pip)
+  - a description on how to reproduce the bug
+  - relevant tool output (e.g., error messages)
+  - data to repoduce the bug (If possible as a GitHub gist. Other platforms like Dropbox, Google Drive links also work. If you can't share the data publicly please indicate this and we will contact you in private.)
+
+If you are an official OpenMS team meber:
+  - label your issue using github labels (e.g. as: question, defect) that indicate the type of issue and which components of autowrap (blue labels) are affected. The severity is usually assigned by OpenMS maintainers and used internally to e.g. indicate if a bug is a blocker for a new release.
+
+# Opening a Pull Request
+
+Before getting started we recommend taking a look at the OpenMS GitHub-Wiki: https://github.com/OpenMS/OpenMS/wiki#-for-developers
+
+Before you open the pull request, make sure you
+ - adhere to [our coding conventions](https://github.com/OpenMS/OpenMS/wiki/Coding-conventions)
+ - have [unit tests and functional tests](https://github.com/OpenMS/OpenMS/wiki/Write-tests)
+ - Have [proper documentation](https://github.com/OpenMS/OpenMS/wiki/Coding-conventions#doxygen)
+
+A core developer will review your changes to the main development branch (develop) and approve them (or ask for modifications). You may indicate the prefered reviewer(s) by adding links to them in a comment section (e.g., @cbielow @hendrikweisser @hroest @jpfeuffer @timosachsenberg)
+
+Also consider getting in contact with the core developers early. They might provide additional guidance and valuable information on how your specific aim is achieved. This might give you a head start in, for example, developing novel tools or algorithms.
+
+Happy coding!

autowrap/CodeGenerator.py

@@ -149,7 +149,7 @@ def __init__(self, resolved, instance_mapping, pyx_target_path=None,
         self.all_classes = self.classes
         self.all_resolved = self.resolved
         if len(allDecl) > 0:
-            
+
             self.all_typedefs = []
             self.all_enums = []
             self.all_functions = []
@@ -191,6 +191,7 @@ def setup_cimport_paths(self):
 
         pxd_dirs = set()
         for inst in self.all_classes + self.all_enums + self.all_functions + self.all_typedefs:
+            # Could this not simply be `for inst in self.all_resolved:` ?
             pxd_path = os.path.abspath(inst.cpp_decl.pxd_path)
             pxd_dir = os.path.dirname(pxd_path)
             pxd_dirs.add(pxd_dir)
@@ -395,7 +396,7 @@ def create_wrapper_for_enum(self, decl, out_codes):
 
     def create_wrapper_for_class(self, r_class, out_codes):
         """Create Cython code for a single class
-        
+
         Note that the cdef class definition and the member variables go into
         the .pxd file while the Python-level implementation goes into the .pyx
         file. This allows us to cimport these classes later across modules.
@@ -718,7 +719,7 @@ def create_wrapper_for_method(self, cdcl, py_name, methods):
                 assert len(methods) == 1, "overloaded operator/= not supported"
                 code = self.create_special_itruediv_method(cdcl, methods[0])
                 return [code], Code.Code()
-            
+
 
         if len(methods) == 1:
             code, typestubs = self.create_wrapper_for_nonoverloaded_method(cdcl, py_name, methods[0])
@@ -1155,7 +1156,7 @@ def create_special_mul_method(self, cdcl, mdcl):
         |    return result
         """, locals())
         return code
-        
+
     def create_special_truediv_method(self, cdcl, mdcl):
         L.info("   create wrapper for operator/")
         assert len(mdcl.arguments) == 1, "operator/ has wrong signature"
@@ -1197,7 +1198,7 @@ def create_special_add_method(self, cdcl, mdcl):
         |    return result
         """, locals())
         return code
-    
+
     def create_special_sub_method(self, cdcl, mdcl):
         L.info("   create wrapper for operator-")
         assert len(mdcl.arguments) == 1, "operator- has wrong signature"
@@ -1302,7 +1303,7 @@ def create_special_imul_method(self, cdcl, mdcl):
         self.top_level_code.append(tl)
 
         return code
-    
+
     def create_special_itruediv_method(self, cdcl, mdcl):
         L.info("   create wrapper for operator/")
         assert len(mdcl.arguments) == 1, "operator/ has wrong signature"
@@ -1535,7 +1536,7 @@ def create_foreign_cimports(self):
         we may be using in this compilation unit. Since we are passing objects
         as arguments quite frequently, we need to know about all other wrapped
         classes and we need to cimport them.
-        
+
         E.g. if we have module1 containing classA, classB and want to access it
         through the pxd header, then we need to add:
 
@@ -1555,7 +1556,7 @@ def create_foreign_cimports(self):
                 for resolved in self.allDecl[module]["decls"]:
 
                     # We need to import classes and enums that could be used in
-                    # the Cython code in the current module 
+                    # the Cython code in the current module
 
                     # use Cython name, which correctly imports template classes (instead of C name)
                     name = resolved.name
@@ -1578,7 +1579,7 @@ def create_foreign_cimports(self):
                             else:
                                 code.add("from $mname cimport $name", locals())
 
-            else: 
+            else:
                 L.info("Skip imports from self (own module %s)" % module)
 
         self.top_level_code.append(code)

autowrap/DeclResolver.py

@@ -79,7 +79,7 @@ class is the same as the name of the C++ class.
         - wrap-manual-memory: will allow the user to provide manual memory
                               management of self.inst, therefore the class will
                               not provide the automated __dealloc__ and inst
-                              attribute (but their presence is still expected). 
+                              attribute (but their presence is still expected).
                               This is useful if you cannot use the shared-ptr
                               approach to store a reference to the C++ class
                               (as with singletons for example).
@@ -229,23 +229,24 @@ class ResolvedFunction(ResolvedMethod):
 
     pass
 
+def resolve_decls_from_files(paths, root, num_processes = 1, cython_warn_level = 1):
+    if num_processes > 1:
+        return resolve_decls_from_files_multi_thread(paths, root, num_processes, cython_warn_level)
+    else:
+        return resolve_decls_from_files_single_thread(paths, root, cython_warn_level)
+
 
-def resolve_decls_from_files_single_thread(pathes, root, cython_warn_level = 1):
+def resolve_decls_from_files_single_thread(paths, root, cython_warn_level = 1):
     decls = []
-    for k, path in enumerate(pathes):
+    for k, path in enumerate(paths):
         full_path = os.path.join(root, path)
-        if k % 50 == 0: 
-            logger.log(25, "parsing progress %s out of %s" % (k, len(pathes)))
+        if k % 50 == 0:
+            logger.log(25, "parsing progress %s out of %s" % (k, len(paths)))
         decls.extend(PXDParser.parse_pxd_file(full_path, cython_warn_level))
     return _resolve_decls(decls)
 
-def resolve_decls_from_files(pathes, root, num_processes = 1, cython_warn_level = 1):
-    if num_processes > 1:
-        return resolve_decls_from_files_multi_thread(pathes, root, num_processes, cython_warn_level)
-    else:
-        return resolve_decls_from_files_single_thread(pathes, root, cython_warn_level)
 
-def resolve_decls_from_files_multi_thread(pathes, root, num_processes, cython_warn_level = 1):
+def resolve_decls_from_files_multi_thread(paths, root, num_processes, cython_warn_level = 1):
     """Perform parsing with multiple threads
 
     This function distributes the work on `num_processes` processes and each
@@ -257,20 +258,20 @@ def resolve_decls_from_files_multi_thread(pathes, root, num_processes, cython_wa
 
     CONCURRENT_FILES_PER_CORE = 10
     pool = mp.Pool(processes=num_processes)
-    full_pathes = [os.path.join(root, path) for path in pathes]
+    full_paths = [os.path.join(root, path) for path in paths]
 
     decls = []
-    while len(full_pathes) > 0:
-        n_work = len(full_pathes)
+    while len(full_paths) > 0:
+        n_work = len(full_paths)
         remaining = max(0, n_work - num_processes * CONCURRENT_FILES_PER_CORE)
-        args = [full_pathes.pop() for k in range(n_work - remaining)]
-        logger.log(25, "parsing progress %s out of %s with %s processes" % (len(pathes)-remaining, len(pathes), num_processes))
+        args = [full_paths.pop() for k in range(n_work - remaining)]
+        logger.log(25, "parsing progress %s out of %s with %s processes" % (len(paths)-remaining, len(paths), num_processes))
         parse_pxd_file_warn = partial(PXDParser.parse_pxd_file, warn_level = cython_warn_level)
         res = pool.map(parse_pxd_file_warn, args)
         for r in res:
             decls.extend(r)
 
-    return _resolve_decls(decls)  
+    return _resolve_decls(decls)
 
 
 def resolve_decls_from_string(pxd_in_a_string):
@@ -280,7 +281,7 @@ def resolve_decls_from_string(pxd_in_a_string):
 def _resolve_decls(decls):
     """
     input:
-        class_decls ist list of instances of PXDParser.BaseDecl.
+        class_decls is a list of instances of PXDParser.BaseDecl.
         (contains annotations
           - about instance names for template parameterized classes
           - about inheritance of methods from other classes in class_decls

autowrap/PXDParser.py

@@ -150,7 +150,7 @@ def parse_line_annotations(node, lines):
                     result[key] += value
       except Exception as e:
         raise ValueError("Cannot parse '{}'".format(line)) from e
-    
+
     # check for multi line annotations after method declaration
     additional_annotations = _parse_multiline_annotations(lines[end:])
     # add multi line doc string to result (overwrites single line wrap-doc, if exists)