Added Python doc resources w/Google,Numpy and reST + comments

Author: calum-bird

README.md

@@ -2,7 +2,9 @@
 This repo contains links to resources related to documentation. It is intended to help you understand the importance of well-written documentation, and simultaneously provide a source of truth for documentation in a given language.
 
 ## Guide
-Just view the LANGUAGEHERE.md file for your preferred language to view associated resources :)
+Just view the \<Language Name\>.md file for your preferred language, or click on it below, to view associated resources that have been compiled thus-far :)
+
+1. [Python](python.md)
 
 ## Don't want to do it yourself?
 Yeah, documentation sucks! That's why we started Trelent. Send us a note at [email protected] and we can discuss automating the documentation for your private repo, or giving your developers the tools to do so at scale!

python.md

@@ -0,0 +1,125 @@
+# Python Documentation
+Documenting Python code is pretty straightforward! It is broken up into two components: comments, and docstrings.
+
+___
+
+## Docstrings
+Python docstrings go by a few main formats, here are the resources for each of those!
+
+### *reStructuredText - PEP 287*
+reStructuredText (reST for short) is a docstring format that leverages the popular plain-text syntax language known as, well, reST. reST ***is not*** exclusively used for Python. This is great, because docstrings written use it gain the ability to be used in the vast ecosystem of reST tools!
+- [CheatSheet](https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst)
+- [Spec](https://www.python.org/dev/peps/pep-0287/)
+
+Example ([thanks, Trelent](https://trelent.net)):
+```python
+def mult_nums(nums):
+    """
+    Multiplies all the numbers in a list of numbers.
+
+    :author: Generated by Trelent
+    :param nums: The list of numbers to multiply.
+    :type nums: list
+    :returns: The product of all the numbers in the list.
+    :rtype: int
+    """
+    result = 1
+    for num in nums:
+        result *= num
+    return result
+```
+
+### *Google*
+The Google format is a python docstring format style that is widely used, but which originated as a part of Google's internal Python styling guide. It is extremely human-readable, and emphasizes this over support for automated tooling.
+- [CheatSheet](https://cheatography.com/sunnyphiladelphia/cheat-sheets/google-style-for-python/)
+- [Spec](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)
+
+Example ([thanks, Sphinx](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html)):
+```python
+def func(arg1, arg2):
+    """Summary line.
+
+    Extended description of function.
+
+    Args:
+        arg1 (int): Description of arg1
+        arg2 (str): Description of arg2
+
+    Returns:
+        bool: Description of return value
+
+    """
+    return True
+```
+
+### *NumPy Docstring Standard*
+The NumPy Docstring standard is a documentation format standardized by the popular open source math library, NumPy. It is also extremely human-readable, and emphasizes this over support for automated tooling.
+- [Spec](https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard)
+
+Example ([thanks, Sphinx](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html)):
+```python
+def func(arg1, arg2):
+    """Summary line.
+
+    Extended description of function.
+
+    Parameters
+    ----------
+    arg1 : int
+        Description of arg1
+    arg2 : str
+        Description of arg2
+
+    Returns
+    -------
+    bool
+        Description of return value
+
+    """
+    return True
+```
+___
+
+## Comments
+Code commenting is super helpful to other developers when used in moderation. Comments should be primarily used to explain the, *ahem*, intricate components of your code.
+
+
+### The do's and don'ts
+___
+Python comments are really simple to use! Just prefix your comment with a `#` character like so:
+```python
+# <Your comment goes here>
+```
+
+A comment can be on its own line:
+```python
+def foo(a,b):
+    # This is a comment!
+    return a+b
+```
+
+A comment can follow a piece of code on the same line:
+```python
+def foo(a,b):
+    return a+b # This is also a comment!
+```
+
+Try not to over-use them, docstrings are meant to explain what a broader snippet of code does, not comments!
+
+**Good example**:
+```python
+def foo(a,b):
+    """Adds together the numbers a and b"""
+    return a+b
+```
+
+**Bad example**:
+```python
+def foo(a,b):
+    # Start with our variables a and b, and add them together
+    c = a+b
+
+    # Great, now return the computed sum as c
+    return c
+```
+___