Fix: feedback from @tupui, @NickleDave

Author: lwasser

documentation/contributing-license-coc.md

@@ -65,8 +65,6 @@ review. Some maintainers may also opt to include the development information in
 ```
 
 
-
-
 ```{tip}
 [The mozilla open workshop has a nice outline of things to consider when 
 creating a contributing guide](https://mozillascience.github.io/working-open-workshop/contributing/)
@@ -84,6 +82,22 @@ by the Open Software Initiative (OSI). OSI's website has a
 
 If you choose your license through GitHub, you can also automatically get a copy of the license file to add to your repository.
 
+### Important: make sure that you closely follow the guidelines outlines by the License that you chose
+
+Every license has different guidelines in terms of what code 
+you can use in your package and also how others can (or can not) use the code in your package. 
+
+If you borrow code from other tools or online sources, make 
+sure that the license for the code that you are using also complies 
+with the license that you selected for your package. 
+
+```{note} 
+An example of code that would not comply with a BSD or MIT license would be any code copied from StackOverflow website. 
+[Stack overflow users a Creative Commons Share Alike license.](https://stackoverflow.com/help/licensing) The sharealike license requires you to use the same sharealike license when you reuse any code from stackoverflow. Thus, if you use code from stack overflow in your package and have a MIT license applied to your package, you are violating stack overflow's license requirements! Proceed with caution here!
+```
+
+[The SciPy documentation has an excellent license discussion that is worth reading and considering for your project's development guide.](https://docs.scipy.org/doc/scipy/dev/core-dev/index.html#licensing)
+
 ## The CODE_OF_CONDUCT.md file
 Your package should have a CODE_OF_CONDUCT.md file located 
 the root of the repository. If you are not comfortable creating 

documentation/index.md

@@ -19,12 +19,11 @@ tools that will help you build your documentation.
 ## Documentation is critical to the success of your Python open source package 
 
 Documentation is as important to the success of your Python open source package 
-as the code itself. Quality code is of course valuable as it gets the tasks 
-that your package seeks to achieve, done. However, if users don't understand 
+as the code itself. Quality code is of course valuable as its how your package gets the tasks done. However, if users don't understand 
 how to use your package in their workflows, then they won't use it. 
 
-Further, if you wish to build a base of contributors to your package, having 
-explicit information about how to contribute is critical.
+Further, explicitly documenting how to contribute is critical if you wish 
+to build a base of contributors to your package. 
 
 ## Documentation elements that pyOpenSci looks for when reviewing a Python package
 

documentation/package-documentation-best-practices.md

@@ -168,6 +168,8 @@ def extent_to_json(ext_obj):
     """
 ```
 
+<!-- I can't seem to get doc targets across pages to work-->
+(docstring_best_practice)=
 ### Best - a docstring with example use of the function
 
 This example contains an example of using the function that is also tested in 
@@ -178,15 +180,16 @@ def extent_to_json(ext_obj):
     """Convert bounds to a shapely geojson like spatial object.
     This format is what shapely uses. The output object can be used
     to crop a raster image.
-    Parameters
+
+        Parameters
     ----------
-    ext_obj: list or geopandas.GeoDataFrame
+    ext_obj : list or geopandas.GeoDataFrame
         If provided with a `geopandas.GeoDataFrame`, the extent
         will be generated from that. Otherwise, extent values
         should be in the order: minx, miny, maxx, maxy.
     Return
     ------
-    extent_json: A GeoJSON style dictionary of corner coordinates
+    extent_json : A GeoJSON style dictionary of corner coordinates
     for the extent
         A GeoJSON style dictionary of corner coordinates representing
         the spatial extent of the provided spatial object.
@@ -198,7 +201,14 @@ def extent_to_json(ext_obj):
     >>> import geopandas as gpd
     >>> import earthpy.spatial as es
     >>> from earthpy.io import path_to_example
+
+	We start by loading a Shapefile.
+
     >>> rmnp = gpd.read_file(path_to_example('rmnp.shp'))
+
+	And then use `extent_to_json` to do the conversion from `shp` to
+    `geopandas.GeoDataFrame`.
+
     >>> es.extent_to_json(rmnp)
     {'type': 'Polygon', 'coordinates': (((-105.4935937, 40.1580827), ...),)}
 

documentation/python-package-documentation-tools.md

@@ -11,7 +11,7 @@ important points page -->
 * Publish your documentation on ReadTheDocs (or GitHub pages if you are more advanced and also prefer to maintain your website locally)
 * Use `myST` syntax to write your documentation 
 * Use sphinx gallery to write tutorials using .py files that automagically have downloadable .py and jupyter notebook files. Use nbsphinx if you prefer writing tutorials in jupyter notebook format and don't need a grid formatted gallery. *Both of these tools will run your tutorials from beginning to end providing an addition layer of testing to your package!*
-
+* OPTIONAL: Use [doctest](https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html) to run the examples in your code's docstrings as a way to make sure that your code's functions and methods (the API) are running as you expect them to. 
 ```
 
 In addition to your:
@@ -125,12 +125,12 @@ Both of these tools act as sphinx extensions and:
 
 ### [sphinx gallery:](https://sphinx-gallery.github.io/stable/index.html) 
 
-If you prefer to write your tutorials using python **.py** scripts, you 
+If you prefer to write your tutorials using Python **.py** scripts, you 
 may enjoy using sphinx gallery. Sphinx gallery uses **.py** files with 
-text and code sections that mimics the Jupyter Notebook format. When you build 
+text and code sections that mimic the Jupyter Notebook format. When you build 
 your documentation, the gallery extension: 
 
-1. Runs the code in each tutorial: this acts as a check to ensure your package is working as you think it is!
+1. Runs the code in each tutorial. Running your tutorial this acts as a check to ensure your package functions and classes (ie the API) are working as they should. 
 1. Creates a downloadable Jupyter Notebook **.ipynb** file and a  **.py** script for your tutorial that a user can quickly download and run. 
 1. Creates a rendered  **.html** page with the code elements and code outputs in a user-friendly tutorial gallery.  
 1. Creates a gallery landing page with visual thumbnails for each tutorial that you create
@@ -248,4 +248,52 @@ _build/
             ...
 ``` 
 
+## Using doctest to run docstring examples in your packages methods and functions
+<!-- This link isn't working no matter how i create the target. not sure 
+why -->
+[In the package documentation page we provided some examples of good, better, best docstring formats](package-documentation-best-practices.html#docstring_best_practice). If you wish, you can also add the [doctest](https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html) extension to your Sphinx build
+as an addition check for docstrings with example code in them. 
+Doctest, runs the example code in your docstring `Examples` checking 
+that the expected output is in fact correct. Similar to running
+tutorials in your documentation, doctest can be a useful step that 
+assures that your packages code (API) runs as you expect it to.
+
+```{note} 
+It's important to keep in mind that examples in your docstrings 
+help users using your package. Running `doctest` on those examples provides a 
+check of your package's API. doctest ensures that the functions and methods in your package 
+run as you expect them to. Neither of these items replace a separate, 
+stand-alone test suite that is designed to test your package's core functionality 
+across operating systems and Python versions. 
+```
+
+Below is an example of a docstring with an example. 
+doctest will run the example below and test that if you provide 
+`add_me` with the values 1 and 3 it will return 4.  
+
+
+```python
+def add_me(aNum, aNum2):
+    """A function that prints a number that it is provided. 
+    
+    Parameters
+    ----------
+    aNum : int
+        An integer value to be printed
+    
+    Returns 
+    -------
+        Prints the integer that you provide the function.
+    
+    """
+   return aNum + aNum2
+
+Examples
+--------
+Below you can see how the `print_me` function will print a number that 
+you provide it.
+
+>>> add_me(1+3)
+4
 
+```