Fix: responded to the 100+ comments left on this pr - phew

Author: lwasser

documentation/hosting-tools/myst-markdown-rst-doc-syntax.md

@@ -2,10 +2,10 @@
 
 There are three commonly used syntaxes for creating Python documentation:
 1. [markdown](https://www.markdownguide.org/): Markdown is an easy-to-learn text 
-syntax. It is the default syntax use in Jupyter Notebooks. There are tools that you can add to a sphinx website that allow it to render markdown as html. However, using markdown to write documentation has limitations. For instance if you want to add references, 
+syntax. It is the default syntax use in Jupyter Notebooks. There are tools that you can add to a Sphinx website that allow it to render markdown as html. However, using markdown to write documentation has limitations. For instance if you want to add references, 
 colored call out blocks and other custom elements to your documentation, you will 
 need to use either **myST** or **rST**.
-1. [rST (ReStructured Text):](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html). **rST** is the native syntax that sphinx supports. rST was the default syntax used for documentation for many years given the limitations of markdown. However, in recent years myST has risen to the top as a favorite for documentation given the flexibility that it allows.
+1. [rST (ReStructured Text):](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html). **rST** is the native syntax that sphinx supports. rST was the default syntax used for documentation for many years. However, in recent years myST has risen to the top as a favorite for documentation given the flexibility that it allows.
 1. [myST:](https://myst-parser.readthedocs.io/en/latest/intro.html) myST is a combination of vanilla of `markdown` and `rST` syntax. It is a nice option if you are comfortable writing markdown. `myst` is preferred by many because it offers both the rich functionality 
 of rST combined with a simple-to-write markdown syntax. 
 
@@ -14,7 +14,7 @@ While you can chose to use any of the syntaxes listed above, we suggest using
 
 * It is a simpler syntax and thus easier to learn;
 * The above simplicity will make it easier for more people to contribute to your documentation. 
-* Most of your core python package text files, such as your README.md file, are already in `.md` format
+* Most of your corePythonpackage text files, such as your README.md file, are already in `.md` format
 * `GitHub` and `Jupyter Notebooks` support markdown thus it's more widely used in the scientific ecosystem. 
 
 

documentation/hosting-tools/sphinx-python-package-documentation-tools.md

@@ -10,7 +10,7 @@ important points page -->
 * Use Sphinx to build your documentation
 * 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!*
+* 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. 
 ``` -->
 
@@ -44,14 +44,14 @@ The functionality of Sphinx can be extended using extensions
 and themes. A few examples include:
 
 * You can apply documentation themes for quick generation of beautiful documentation.
-* You can [automatically create documentation for your package's functions and classes (that package's API) from docstrings in your code using the autodoc extension](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html)
+* You can [automatically create documentation for your package's functions and classes (the package's API) from docstrings in your code using the autodoc extension](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html)
 * You can [run and test code examples in your docstrings using the doctest extension](https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html)
-* While sphinx natively supports the `rST` syntax. You can add custom syntax parsers to support easier-to-write syntax using tools such as [myst](https://myst-parser.readthedocs.io/).
+* While Sphinx natively supports the `rST` syntax. You can add custom syntax parsers to support easier-to-write syntax using tools such as [the MyST parser](https://myst-parser.readthedocs.io/).
 
-### Commonly used sphinx themes 
+### Commonly used Sphinx themes 
 
-You are free to use whatever sphinx theme that you prefer. 
-However, the most common sphinx themes used in the Python 
+You are free to use whatever Sphinx theme that you prefer. 
+However, the most common Sphinx themes used in the Python 
 scientific community include:  
 
 * [pydata-sphinx-theme](https://pydata-sphinx-theme.readthedocs.io/) 

documentation/hosting-tools/website-hosting-optimizing-your-docs.md

@@ -1,7 +1,7 @@
 # Optimizing your documentation so search engines (and other users) find it
 
 If you are interested in more people finding your package, you may want to 
-add some core sphinx extensions (and theme settings) that will help search 
+add some core Sphinx extensions (and theme settings) that will help search 
 engines such as Google find your documentation. 
 
 ### Google Analytics
@@ -34,7 +34,7 @@ more visible to others when they search.
 
 This extension is lightweight.
 
-It [requires that you to add it to your sphinx `conf.py` extension list and site your documentation base url.](https://sphinx-sitemap.readthedocs.io/en/latest/getting-started.html).
+It [requires that you to add it to your Sphinx `conf.py` extension list and site your documentation base url.](https://sphinx-sitemap.readthedocs.io/en/latest/getting-started.html).
 
 ### [sphinxext.opengraph](https://github.com/wpilibsuite/sphinxext-opengraph)
 

documentation/index.md

@@ -30,7 +30,7 @@ Your package should at a minimum have:
 * CODE_OF_CONDUCT.md 
 * LICENSE.txt 
 * User-facing documentation website with tutorials 
-* API documentation (often found in the user facing documentation website)
+* API documentation (often found in the user-facing documentation website)
 
 The pages in this section of our guide provide you with more 
 detail about creating each of the above elements. We also suggest 
@@ -79,7 +79,7 @@ look for are listed below.
 1. Individual files in your GitHub (or GitLab) repository including:
     * [A clear and to the point **README.md** file](readme-file-best-practices) that includes information about how to cite your package.
     * A [**CONTRIBUTING.md** file](contributing-license-coc) that outlines how others can contribute to your package. This file should also link to your development guide and code of conduct. A well-crafted contributing guide will make it much easier for the community to contribute to your project.
-    * A [**CODE_OF_CONDUCT.md**](contributing-license-coc.html#the-code-of-conduct-md-file) file. This file sets up the guidelines for how your community interacts. It ideally ensures that everyone feels safe and can report inappropriate behavior if need be.   <!--<not sure why header targets aren't working here with sphinx they work online> -->
+    * A [**CODE_OF_CONDUCT.md**](contributing-license-coc.html#the-code-of-conduct-md-file) file. This file sets up the guidelines for how your community interacts. It ideally ensures that everyone feels safe and can report inappropriate behavior if need be.   <!--<not sure why header targets aren't working here with Sphinx they work online> -->
     * [**A LICENSE.txt file**](contributing-license-coc.html#your-repository-should-have-a-license-md-file) A license file declaring the OSI-approved license that you select and instructions for citing your package.
     * We also suggest (but don't require) that you include a development guide that details the infrastructure used in your package. Sometimes this file is included in the user-facing documentation website (discussed below).  
 1. [**User focused package documentation**](package-documentation-best-practices) that helps users understand how to install, setup and use your package. Documentation is most often contained in a stand-alone website. The user-focused documentation should include:
@@ -91,7 +91,7 @@ look for are listed below.
 ---
 name: directive-fig
 width: 80%
-alt: Image showing the files in the Moving Pandas GitHub repository. 
+alt: Image showing that the MovingPandas GitHub repository has the required package health files. 
 ---
 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,18 +105,20 @@ 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.
 ---
 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)*
 ```
 
-SNYK is another well-known company that keeps tabs on package health.
+[Snyk](https://snyk.io/advisor/python) is another well-known company that keeps tabs on package health.
 Below you can see a similar evaluation of files in the Github repo as a 
 measure of community health. 
 
 ```{figure} ../images/moving-pandas-python-package-snyk-health.png
 ---
 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.
 ---
 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/code-of-conduct-file.md

@@ -31,4 +31,4 @@ If you are not comfortable
 with creating your own code of conduct text, we encourage you to adopt the 
 code of conduct language used in the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). 
 [Many other communities](https://www.contributor-covenant.org/adopters/) have adopted this code of conduct as 
-their own including the [Fatiando](https://github.com/fatiando/community/blob/main/CODE_OF_CONDUCT.md) scientific geoscience community.  
+their own. See the [Fatiando a Terra Geoscience Python community's example here.](https://github.com/fatiando/community/blob/main/CODE_OF_CONDUCT.md)

documentation/repository-files/development-guide.md

@@ -28,7 +28,7 @@ documented in the case that we need to help you onboard new
 maintainers in the future. 
 
 ```{note}
-A well thought-out continuous integration setup in your repository 
+A well thought out continuous integration setup in your repository 
 can allow users to skip building the package locally (especially if they are just updating text).
 ``` 
 
@@ -40,7 +40,7 @@ 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 
+[The Mozilla Science Lab website has a nice outline of things to consider when 
 creating a contributing guide](https://mozillascience.github.io/working-open-workshop/contributing/)
 ```
 

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

@@ -1,16 +1,17 @@
 # README File Guidelines and Resources
 
-The **README.md** file is often the first thing that someone sees before they
-install your package. 
+Your **README.md** file should be located in the root of your GitHub repository. 
+The **README.md** file is important as it is often the first thing that someone 
+sees before they install your package. 
 
 The README.md file is the landing page of:
 
-* Your package's landing page on a repository site such as PyPI or Anaconda
+* Your package as it appears on a repository site such as PyPI or Anaconda
 * Your package's GitHub repository
 
 Your README.md file is also used as a measure of package and community 
 health on sites such as:
-* [GitHub community health for MovingPandas (available for all repositories)](https://github.com/anitagraser/movingpandas/community) and [snyk - moving pandas example](https://snyk.io/advisor/python/movingpandas)  
+* [GitHub community health for MovingPandas (available for all repositories)](https://github.com/anitagraser/movingpandas/community) and [Snyk - moving pandas example](https://snyk.io/advisor/python/movingpandas)  
 
 
 ```{figure} /images/pandera-python-package-readme-github.png
@@ -24,8 +25,6 @@ Your GitHub repository landing page highlights the README.md file. Here you can
 Thus, it is important that you spend some time up front creating a high quality 
 **README.md** file for your Python package.
 
-Your README.md file should be located in the root of your GitHub repository. 
-
 ````{note}
 An editor or the editor in chief will ask you to revise your README file
 before a review begins if it does not meet the criteria specified below. 
@@ -68,7 +67,7 @@ README file for others to quickly browse.
 
 Some badges that you might consider adding to your README file include:
 
-* Current version of the package on pypi / conda 
+* Current version of the package on PyPI / Anaconda Cloud 
 
 Example: [![PyPI version shields.io](https://img.shields.io/pypi/v/pandera.svg)](https://pypi.org/project/pandera/)
 
@@ -104,22 +103,22 @@ or complementary package mentions them here in 1-2 sentences.
 
 ```{tip}
 Consider writing for a high school level (or equivalent) level. This 
-level of writing is often consider level for scientific content that 
+level of writing is often considered an appropriate level for scientific content that 
 serves a variety of users with varying backgrounds. 
 
-The goal of this description to maximize 
-accessibility of your **README** file.
+The goal of this description is to maximize accessibility of your **README** 
+file.
 ```
 
 ### ✔️ Installation instructions
 
 Include instructions for installing your package. If you have published 
-the package on both PyPI and Conda be sure to include instructions for both. 
+the package on both PyPI and Anaconda Cloud be sure to include instructions for both. 
 
 ### ✔️ Document any addition setup required
 
 Add any additional setup required such as authentication tokens, to 
-get started using your package. If setup is complex, consider linking to a 
+get started using your package. If setup is complex, consider linking to an 
 installation page in your online documentation here rather than over complicating
 your README file. 
 
@@ -170,7 +169,7 @@ and any language that you'd like to see associated with the citation.
 Below are some resources on creating great README.md files that you 
 might find helpful.
 
-* [Write a great readme - Bane Sullivan](https://github.com/banesullivan/README)
-* [The art of the README GitHub Repo](https://github.com/hackergrrl/art-of-readme)
+* [How to Write a Great README - Bane Sullivan](https://github.com/banesullivan/README)
+* [Art of README - Kira (@hackergrrl)](https://github.com/hackergrrl/art-of-readme)
 
 ```

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

@@ -1,37 +1,37 @@
 # Create tutorials in your Python package documentation 
 
 <!-- TODO: modify the nbsphinx example to use nbgallery 
-as a front end vs sphinx gallery - will look better that way
+as a front end vs Sphinx gallery - will look better that way
 -->
 Your package should have tutorials that make it easy for a user 
 to get started using your package. Ideally, those tutorials 
 also can be run from start to finish providing a second set of 
 checks (on top of your test suite) to your package's code base. 
 
-In the [documentation tools page](python-package-documentation-tools) we talk about two sphinx extensions (`sphinx-gallery` and `nbsphinx`)
+In the [documentation tools page](python-package-documentation-tools) we talk about two Sphinx extensions (`sphinx-gallery` and `nbsphinx`)
 that  allow you to create reproducible tutorials that are run 
-when your sphinx documentation builds. 
+when your Sphinx documentation builds. 
 
-## Create python package tutorials that both help users and test your package's code
+## CreatePythonpackage tutorials that both help users and test your package's code
 
 Adding well constructed tutorials to your package will make it easier for someone 
 new to begin using your package. 
 
-There are two sphinx tools that make it easy to add tutorials to your package:
+There are two Sphinx tools that make it easy to add tutorials to your package:
 
 * [Sphinx Gallery](https://sphinx-gallery.github.io/stable/index.html) and 
 * [NbSphinx](https://nbsphinx.readthedocs.io/en/latest/)
 
-Both of these tools act as sphinx extensions and:
+Both of these tools act as Sphinx extensions and:
 
-* Support creating a gallery type page in your sphinx documentation where users can explore tutorials via thumbnails.
+* Support creating a gallery type page in your Sphinx documentation where users can explore tutorials via thumbnails.
 * Run the code in your tutorials adding another level of "testing" for your package as used. 
 * Render your tutorials with Python code and plot outputs
 
 ### [sphinx gallery:](https://sphinx-gallery.github.io/stable/index.html) 
 
 If you prefer to write your tutorials using Python **.py** scripts, you 
-may enjoy using sphinx gallery. Sphinx gallery uses **.py** files with 
+may enjoy using Sphinx gallery. Sphinx gallery uses **.py** files with 
 text and code sections that mimic the Jupyter Notebook format. When you build 
 your documentation, the gallery extension: 
 
@@ -57,7 +57,7 @@ Below you can see what a tutorial looks like created with sphinx-gallery.
 ---
 name: directive-fig
 width: 80%
-alt: Image showing ta single tutorial from sphinx gallery. The tutorial shows a simple matplotlib created plot and associated code. 
+alt: Image showing ta single tutorial from Sphinx gallery. The tutorial shows a simple matplotlib created plot and associated code. 
 ---
 `sphinx-gallery` tutorials by default include download links for both the 
 python script (**.py** file) and a Jupyter notebook (**.ipynb** file) at the bottom. 
@@ -71,7 +71,7 @@ python script (**.py** file) and a Jupyter notebook (**.ipynb** file) at the bot
 
 #### Sphinx gallery challenges 
 
-The downsides of using sphinx gallery include: 
+The downsides of using Sphinx gallery include: 
 
 * the **.py** files can be finicky to configure, particularly if you have matplotlib plot outputs. 
 
@@ -114,7 +114,7 @@ _build/
 ### [nbsphinx - tutorials using Jupyter Notebooks](https://nbsphinx.readthedocs.io/en/latest/)
 
 If you prefer to use Jupyter Notebooks to create tutorials you can use nbsphinx.
-nbsphinx operates similarly to sphinx gallery in that:
+nbsphinx operates similarly to Sphinx gallery in that:
 
 * It runs your notebooks and produces outputs in the rendered tutorials 
 
@@ -128,7 +128,7 @@ name: directive-fig
 width: 80%
 alt: Image showing the gallery output provided by nbsphinx using the sphinx-gallery front end interface. 
 ---
-`nbsphinx` can be combined with sphinx gallery to create a gallery of tutorials. 
+`nbsphinx` can be combined with Sphinx gallery to create a gallery of tutorials. 
 However, rather render the gallery as a grid, it lists all of the gallery 
 elements in a single column. 
 ```
@@ -144,7 +144,7 @@ _build/
         # Notice that nbsphinx runs each notebook and produces an 
         # html file with all of the outputs of your code 
         # you can link to the notebook in your docs by modifying 
-        # the nbsphinx build - we will cover this in a separate tutorial series focused on python packaging!
+        # the nbsphinx build - we will cover this in a separate tutorial series focused onPythonpackaging!
         tutorials/ 
             index.html
             index.md