Fix: more fixes from @sneakers-the-rat review and @NickleDave review

Author: lwasser

documentation/hosting-tools/publish-documentation-online.md

@@ -7,10 +7,38 @@ quickly create a documentation website hosting environment are below.
 1. You can host your documentation yourself using [GitHub Pages](https://pages.github.com/) or another online hosting service. 
 1. You can host your documentation using [Read the Docs](https://readthedocs.org/).
 
-If you don't want to maintain a documentation website for your Python package, 
-we suggest using the Read the Docs website. Read the Docs allows you to:
+## What is Read the Docs ?
+[Read the Docs](https://readthedocs.org/) is a documentation hosting service that supports publishing your project's documentation. 
+
+Read the Docs is a fully featured, free, documentation hosting 
+service. Some of its many features include:
 
-* Quickly launch a website using the documentation found in your GitHub repository.  
-* Track versions of your documentation as you release updates.
-* Provides support for Google analytics.
+* Is free to host your documentation (but there are also paid tiers if you wish to customize hosting)
+* Automates building your documentation 
 * Allows you to turn on integration with pull requests where you can view documentation build progress (success vs failure).
+* Supports versioning of your documentation which allows users to refer to older tagged versions of the docs if they are using older versions of your package. 
+* Supports downloading of documentation in PDF and other formats. 
+* You can customize the documentation build using a **.readthedocs.yaml** file in your GitHub repository. 
+
+
+## What is GitHub Pages?
+[GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages) is a free web 
+hosting service offered by GitHub. Using GitHub pages, you can build your 
+documentation locally or using a Continuous Integration setup, and then push 
+to a branch in your GitHub repository that is setup to run the GitHub Pages 
+web build.  
+
+
+
+## Read the Docs vs GitHub Pages 
+
+GitHub pages is a great option for your documentation deployment. 
+However, you will need to do a bit more work to build and deploy your 
+documentation if you use GitHub pages. 
+
+Read the Docs can be setup in your Read the Docs user account. The service 
+and automates the entire process of building and deploying your documentation. 
+
+If you don't want to maintain a documentation website for your Python package, 
+we suggest using the Read the Docs website.
+

documentation/index.md

@@ -91,7 +91,8 @@ look for are listed below.
 ---
 name: directive-fig
 width: 80%
-alt: Image showing that the MovingPandas GitHub repository has the required package health files. 
+alt: Image showing the files in the the MovingPandas GitHub repository. Files there include code of conduct.md,
+Contributing.md, license.txt, readme.md. 
 ---
 An example from the MovingPandas GitHub repository with all of the major files in it including CONTRIBUTING.md, README.md, CODE_OF_CONDUCT.md and a LICENSE.txt file. *(screen shot taken Nov 23 2022)*
 ```
@@ -105,7 +106,7 @@ standards page that everyone has in their GitHub repository.
 ---
 name: directive-fig
 width: 80%
-alt: Image showing that the MovingPandas GitHub repository community health page with green checks next to each file.
+alt: Image showing that the MovingPandas GitHub repository community health page with green checks next to each file including: description, README, code of conduct, contributing, license and issue templates. Note that Security policy has a yellow circle next to it as that is missing from the repo.
 ---
 GitHub community health looks for a readme file among other elements when it evaluates the community level health of your repository. This example is from the [MovingPandas GitHub repo](https://github.com/anitagraser/movingpandas/community) *(screen shot taken Nov 23 2022)*
 ```
@@ -118,7 +119,7 @@ measure of community health.
 ---
 name: directive-fig
 width: 80%
-alt: Screenshot of the Snyk page for movingpandas, that indicates the community is active, that it has a readme, contributing.md, and code of conduct. The page also shows 30 contributors and no funding.
+alt: Screenshot of the Snyk page for movingpandas. It shows that the repository has a README file, contributing file, code of conduct. It also shows that it has 30 contributors and no funding. The package health score is 78/100.
 ---
 Screenshot showing [SNYK](https://snyk.io/advisor/python/movingpandas) package health for moving pandas. Notice both platforms look for a README file. *(screen shot taken Nov 23 2022)*
 ```

documentation/repository-files/readme-file-best-practices.md

@@ -18,6 +18,10 @@ health on sites such as:
 ---
 name: directive-fig
 width: 80%
+alt: README landing page screenshot for the Pandera package. It has the pandera logo at the top - which has two arrows in a chevron pattern pointing downward within a circle. Subtitle: statistical data testing toolkit. A data validation library for scientists, engineering, and analytics seeking correctness. 
+Below that are a series of badges including CI tests passing, docs passing, version of pandera on pypi (0.13.4), MIT license and that it has been pyOpenSci peer reviewed. There are numerous badges below that. 
+Finally below the badges the text reads:
+Pandera provides a flexible and expressive API for performing data validation on dataframe-like objects to make data processing pipelines more readable and robust.
 ---
 Your GitHub repository landing page highlights the README.md file. Here you can see the README.md file for the pyOpenSci package [Pandera](https://github.com/unionai-oss/pandera). *(screen shot taken Nov 23 2022)*
 ```
@@ -59,7 +63,7 @@ self explanatory that name is, the better.
 Badges are a useful way to draw attention to the quality of your project. Badges 
 assure users that your package is well-designed, tested, and maintained. They 
 are also a useful maintenance tool to evaluate if things are building properly. 
-A great example of this is adding a readthedocs badge to your readme to quickly
+A great example of this is adding a [Read the Docs status badge](https://docs.readthedocs.io/en/stable/badges.html) to your README.md file to quickly
 see when the build on that site fails. 
 
 It is common to provide a collection of badges towards the top of your 

documentation/write-user-documentation/create-package-tutorials.md

@@ -12,7 +12,7 @@ In the [documentation tools page](python-package-documentation-tools) we talk ab
 that  allow you to create reproducible tutorials that are run 
 when your Sphinx documentation builds. 
 
-## CreatePythonpackage tutorials that both help users and test your package's code
+## Create Python package tutorials that run when you build your docs
 
 Adding well constructed tutorials to your package will make it easier for someone 
 new to begin using your package. 

documentation/write-user-documentation/document-your-code-api-docstrings.md

@@ -66,9 +66,11 @@ to properly read and format NumPy format docstrings.
 ### Docstring examples Better and Best 
 
 Below is a good example of a well documented function. Notice that this 
-function's docstring describes every function inputs and the function's output 
-(or return value). The description of the function is short and to the point 
-(2 to 3 sentences). And the return of the function is specified. 
+function's docstring describes the function's inputs and the function's output 
+(or return value). The initial description of the function is short (one line). 
+Following that single line description there is a slightly longer description of 
+what the function does (2 to 3 sentences). The return of the function is also
+specified. 
 
 ```Python
 def extent_to_json(ext_obj):
@@ -113,8 +115,9 @@ def extent_to_json(ext_obj):
         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
-    ------
+
+    Returns
+    -------
     extent_json : A GeoJSON style dictionary of corner coordinates
     for the extent
         A GeoJSON style dictionary of corner coordinates representing
@@ -147,7 +150,7 @@ def extent_to_json(ext_obj):
 name: directive-fig
 width: 80%
 ---
-Using the above NumPy format  docstring in sphinx, the autodoc extension will 
+Using the above NumPy format docstring in sphinx, the autodoc extension will 
 create the about documentation section for the `extent_to_json` function. The 
 output of the `es.extent_to_json(rmnp)` command can even be tested using 
 doctest adding another quality check to your package. 

documentation/write-user-documentation/get-started.md

@@ -12,11 +12,20 @@ Your package:
 ``` -->
 
 ## Core components of user-facing Python package documentation 
-Your user-facing documentation for your Python package should include several core components: 
+Below we break documentation into two broad types.
+
+**User-facing documentation **refers to documentation that describes the way the 
+tools within a package is broadly used in workflows. **API documentation, documentation of your functions, classes and methods in your code,** is written 
+at a more granular level. It is documentation for each specific function, class, 
+method or attribute that a user can use in the package. this is the documentation 
+that a user sees when they type `help(function-name)`. 
+
+Your user-facing documentation for your Python package should include several 
+core components. 
 
 * **Documentation Website:** This refers to easy-to-read documentation that helps someone use your package. This documentation should help users both install and use your package.
 * **Short Tutorials:** Your user-facing documentation should also include [**short tutorials** that show case core features of your package](create-package-tutorials).   
-* **Package Code / API documentation:** You packages functions and methods (the API) should also be documented. API documentation can be generated from [docstrings](https://pandas.pydata.org/docs/development/contributing_docstring.html) found in your 
+* **Package Code / API documentation:** You package's functions, methods, attributes and classes (the API) should also be documented. API documentation can be generated from [docstrings](https://pandas.pydata.org/docs/development/contributing_docstring.html) found in your 
 code. Ideally, you have docstrings for all user-facing functions, methods and classes in 
 your Python package. [We discuss code documentation and docstrings in greater detail here.](document-your-code-api-docstrings)