Documenting your code

Docstrings

All functions and classes in this library should contain docstrings. Although Sphinx requires using the reStructuredText format for docstrings, we will be using Google style docstrings as they provide a clearer interface. We can easily convert these into reStructuredText when generating docs with Sphinx, by using extensions such as napoleon.

Here's a comparison of the different styles:

1. Google style

def sample_function_google(a, b):  
	"""Google style  
	  
	Args:  
		a:  
		b:  
	  
	Returns:  
	  
	"""

2. Numpy style

def sample_function_numpy(a, b):  
	"""Numpy style  
	  
	Parameters  
	----------  
	a  
	b  
	  
	Returns  
	-------  
	  
	"""

3. Sphinx (reStructuredText) style:

def test_function_restructured_text(a, b):  
	"""reStructuredText style  
	  
	:param a:  
	:param b:  
	:return:  
	"""

Typehints

Make sure to include type hints in all your class and function definitions.