Merge pull request #152 from ReactionMechanismGenerator/docs

ARC's documentation

.gitignore

@@ -34,3 +34,6 @@ scratch/
 
 # iPython files
 *.ipynb_*
+
+# Compiled documentation
+docs/build/*

CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# RMG Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at alongd@mit.edu. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct/
+
+[homepage]: https://www.contributor-covenant.org
+

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2018 Alon Grinberg Dana
+Copyright (c) 2018-2019 Alon Grinberg Dana
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

arc/common.py

@@ -2,8 +2,12 @@
 # encoding: utf-8
 
 """
-ARC's common module
-This module should not import any other module that has logging to avoid circular imports.
+This module contains functions which are shared across multiple ARC modules.
+As such, it should not import any other ARC module (specifically ones that use logging) to avoid circular imports.
+
+VERSION is the full ARC version, using `semantic versioning <https://semver.org/>`_.
+
+ATOM_RADII data taken from `DOI 10.1039/b801115j <http://dx.doi.org/10.1039/b801115j>`_.
 """
 
 from __future__ import (absolute_import, division, print_function, unicode_literals)
@@ -40,7 +44,7 @@ def time_lapse(t0):
         t0 (time.pyi): The initial time the count starts from.
 
     Returns:
-        str, unicode: A "D HH:MM:SS" formatted time difference between now and t0.
+        str: A "D HH:MM:SS" formatted time difference between now and t0.
     """
     t = time.time() - t0
     m, s = divmod(t, 60)
@@ -98,9 +102,9 @@ def initialize_log(log_file, project, project_directory=None, verbose=logging.IN
     Set up a logger for ARC.
 
     Args:
-        log_file (str, unicode): The log file name.
-        project (str, unicode): A name for the project.
-        project_directory (str, unicode, optional): The path to the project directory.
+        log_file (str): The log file name.
+        project (str): A name for the project.
+        project_directory (str, optional): The path to the project directory.
         verbose (int, optional): Specify the amount of log text seen.
     """
     # backup and delete an existing log file if needed
@@ -161,7 +165,7 @@ def log_header(project, level=logging.INFO):
     Output a header containing identifying information about ARC to the log.
 
     Args:
-        project (str, unicode): The ARC project name to be logged in the header.
+        project (str): The ARC project name to be logged in the header.
         level: The desired logging level.
     """
     logger.log(level, 'ARC execution initiated on {0}'.format(time.asctime()))
@@ -198,8 +202,7 @@ def get_git_commit():
         Returns empty strings if hash and date cannot be determined.
 
     Returns:
-        str, unicode: The git HEAD commit hash.
-        str, unicode: The git HEAD commit date.
+        tuple: The git HEAD commit hash and the git HEAD commit date, each as a string.
     """
     if os.path.exists(os.path.join(arc_path, '.git')):
         try:
@@ -215,7 +218,7 @@ def get_git_branch():
     Get the git branch to be logged.
 
     Returns:
-        str, unicode: The git branch name.
+        str: The git branch name.
     """
     if os.path.exists(os.path.join(arc_path, '.git')):
         try:
@@ -234,7 +237,7 @@ def log_footer(execution_time, level=logging.INFO):
     Output a footer for the log.
 
     Args:
-        execution_time (str, unicode): The overall execution time for ARC.
+        execution_time (str): The overall execution time for ARC.
         level: The desired logging level.
     """
     logger.log(level, '')
@@ -248,10 +251,10 @@ def read_yaml_file(path):
     and return the parameters as python variables.
 
     Args:
-        path (str, unicode): The YAML file path to read.
+        path (str): The YAML file path to read.
 
     Returns:
-        dict, list: The content read from the file.
+        dict or list: The content read from the file.
     """
     if not os.path.isfile(path):
         raise InputError('Could not find the YAML file {0}'.format(path))
@@ -265,8 +268,8 @@ def save_yaml_file(path, content):
     Save a YAML file (usually an input / restart file, but also conformers file)
 
     Args:
-        path (str, unicode): The YAML file path to save.
-        content (str, unicode): The content to save.
+        path (str): The YAML file path to save.
+        content (str): The content to save.
     """
     yaml.add_representer(str, string_representer)
     yaml.add_representer(unicode, unicode_representer)
@@ -277,14 +280,18 @@ def save_yaml_file(path, content):
 
 
 def string_representer(dumper, data):
-    """Add a custom string representer to use block literals for multiline strings"""
+    """
+    Add a custom string representer to use block literals for multiline strings.
+    """
     if len(data.splitlines()) > 1:
         return dumper.represent_scalar(tag='tag:yaml.org,2002:str', value=data, style='|')
     return dumper.represent_scalar(tag='tag:yaml.org,2002:str', value=data)
 
 
 def unicode_representer(dumper, data):
-    """Add a custom unicode representer to use block literals for multiline strings"""
+    """
+    Add a custom unicode representer to use block literals for multiline strings in unicode.
+    """
     if len(data.splitlines()) > 1:
         return yaml.ScalarNode(tag='tag:yaml.org,2002:str', value=data, style='|')
     return yaml.ScalarNode(tag='tag:yaml.org,2002:str', value=data)
@@ -298,7 +305,7 @@ def get_ordinal_indicator(number):
         number (int): An integer for which the ordinal indicator will be determined.
 
     Returns:
-        str, unicode: The integer's ordinal indicator.
+        str: The integer's ordinal indicator.
     """
     ordinal_dict = {1: 'st', 2: 'nd', 3: 'rd'}
     if number > 13:
@@ -308,7 +315,6 @@ def get_ordinal_indicator(number):
     return 'th'
 
 
-# ATOM_RADII data taken from DOI: 10.1039/b801115j
 ATOM_RADII = {'H': 0.31, 'He': 0.28,
               'Li': 1.28, 'Be': 0.96, 'B': 0.84, 'C': 0.76, 'N': 0.71, 'O': 0.66, 'F': 0.57, 'Ne': 0.58,
               'Na': 1.66, 'Mg': 1.41, 'Al': 1.21, 'Si': 1.11, 'P': 1.07, 'S': 1.05, 'Cl': 1.02, 'Ar': 1.06,
@@ -327,7 +333,7 @@ def get_atom_radius(symbol):
     (Change to QCElemental after transitioning to Py3)
 
     Args:
-        symbol (str, unicode): The atomic symbol.
+        symbol (str): The atomic symbol.
 
     Returns:
         float: The atomic covalent radius (None if not found).
@@ -351,6 +357,7 @@ def determine_symmetry(coords, symbols):
 
     Returns:
         int: The external symmetry number.
+    Returns:
         int: 1 if no chiral centers are present, 2 if chiral centers are present.
     """
     atom_numbers = list()  # List of atomic numbers
@@ -380,7 +387,9 @@ def determine_symmetry(coords, symbols):
 
 
 def min_list(lst):
-    """A helper function for finding the minimum of a list of integers where some of the entries might be None"""
+    """
+    A helper function for finding the minimum of a list of integers where some of the entries might be None.
+    """
     if len(lst) == 0:
         return None
     elif len(lst) == 1: