some user-documentation improvements

ucodery · lwasser · commit 34d85c7737a1 · 2023-05-15T19:53:36.000-06:00
diff --git a/documentation/hosting-tools/myst-markdown-rst-doc-syntax.md b/documentation/hosting-tools/myst-markdown-rst-doc-syntax.md
@@ -2,7 +2,7 @@
 
 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 used 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. However, in recent years myST has risen to the top as a favorite for documentation given the flexibility that it allows.
@@ -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 corePythonpackage text files, such as your README.md file, are already in `.md` format
+* Most of your core Python package 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.
 
 
diff --git a/documentation/hosting-tools/publish-documentation-online.md b/documentation/hosting-tools/publish-documentation-online.md
@@ -37,7 +37,7 @@ 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.
+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.
diff --git a/documentation/hosting-tools/website-hosting-optimizing-your-docs.md b/documentation/hosting-tools/website-hosting-optimizing-your-docs.md
@@ -8,7 +8,7 @@ engines such as Google find your documentation.
 
 ```{important}
 
-Google analytics [is not compliant with the European General Data Protection Regulation (GDPR)](https://matomo.org/blog/2022/05/google-analytics-4-gdpr/). While there are many components to this regulation, one of the core elements is that you have to let users know on your site that you are collecting data and they have to consent. WHile it is possible to add infrastructure around Google Analytics to make it close to following GDPR regulations, the community is slowly shifting away from Google using open tools such as [Plausible](https://plausible.io/), [Cloudflare Web Analytics](https://www.cloudflare.com/web-analytics/) and [Matomo](https://matomo.org) for web analytics.
+Google analytics [is not compliant with the European General Data Protection Regulation (GDPR)](https://matomo.org/blog/2022/05/google-analytics-4-gdpr/). While there are many components to this regulation, one of the core elements is that you have to let users know on your site that you are collecting data and they have to consent. While it is possible to add infrastructure around Google Analytics to make it close to following GDPR regulations, the community is slowly shifting away from Google using open tools such as [Plausible](https://plausible.io/), [Cloudflare Web Analytics](https://www.cloudflare.com/web-analytics/) and [Matomo](https://matomo.org) for web analytics.
 
 pyOpenSci is currently looking into free options for open source
 developers.
@@ -35,7 +35,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)
 
diff --git a/documentation/repository-files/readme-file-best-practices.md b/documentation/repository-files/readme-file-best-practices.md
@@ -116,7 +116,7 @@ file.
 Include instructions for installing your package. If you have published
 the package on both PyPI and Anaconda Cloud be sure to include instructions for both.
 
-### ✔️ Document any addition setup required
+### ✔️ Document any additional setup required
 
 Add any additional setup required such as authentication tokens, to
 get started using your package. If setup is complex, consider linking to an
diff --git a/documentation/write-user-documentation/create-package-tutorials.md b/documentation/write-user-documentation/create-package-tutorials.md
@@ -35,10 +35,10 @@ 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:
 
-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. Runs the code in each tutorial. Running your tutorial like this acts as a check to ensure your package's functions, classes, methods, and attributes (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
+1. Creates a gallery landing page with visual thumbnails for each tutorial that you create.
 
 
 ```{figure} /images/sphinx-gallery-overview.png
@@ -64,26 +64,26 @@ python script (**.py** file) and a Jupyter notebook (**.ipynb** file) at the bot
 ```
 
 ### Sphinx Gallery benefits
-* easy-to-download notebook and .py outputs for each tutorials
+* easy-to-download notebook and .py outputs for each tutorials.
 * .py files are easy to work with in the GitHub pull request environment.
-* Nice gridded gallery output
-* Build execution time data per tutorial [Example](https://sphinx-gallery.github.io/stable/auto_examples/sg_execution_times.html)
+* Nice gridded gallery output.
+* Build execution time data per tutorial. [Example](https://sphinx-gallery.github.io/stable/auto_examples/sg_execution_times.html)
 
 #### Sphinx gallery challenges
 
 The downsides of using Sphinx gallery include:
 
 * the **.py** files can be finicky to configure, particularly if you have matplotlib plot outputs.
 
-For example: To make allow for plots to render, you need to name each file with `plot_`
+For example: To allow for plots to render, you need to name each file with `plot_`
 at the beginning.
 
 * Many users these days are used to working in Jupyter Notebooks. .py may be slightly less user friendly to work with
 
 These nuances can make it challenging for potential contributors to add
 tutorials to your package. This can also present maintenance challenge.
 
-Add about the gallery setup -
+Add about the gallery setup:
 
 ```bash
 $ docs % make html
@@ -129,7 +129,7 @@ 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.
-However, rather render the gallery as a grid, it lists all of the gallery
+However, rather than rendering the gallery as a grid, it lists all of the gallery
 elements in a single column.
 ```
 
diff --git a/documentation/write-user-documentation/document-your-code-api-docstrings.md b/documentation/write-user-documentation/document-your-code-api-docstrings.md
@@ -4,15 +4,15 @@
 
 API stands for **A**pplied **P**rogramming **I**nterface. When
 discussed in the context of a (Python) package, the API refers to
-the functions, methods and classes that a package maintainer creates for users.
+the functions, classes, methods, and attributes that a package maintainer creates for users.
 
 A simple example of a package API element:
 For instance, a package might have a function called `add_numbers()`
 that adds up a bunch of numbers. To add up numbers, you as the user
 simply call `add_numbers(1,2,3)` and the package function calculates the value and returns `6`. By calling the `add_numbers` function, you are
 using the package's API.
 
-Package APIs consist of functions and/or classes, methods and attributes that create a user interface (known as the API).
+Package APIs consist of functions, classes, methods and attributes that create a user interface.
 
 ## What is a docstring and how does it relate to documentation?
 
@@ -21,11 +21,11 @@ that describes what the function does and its inputs and outputs. Python program
 
 The docstring is thus important for:
 
-- When you call `help()` in Python, for example, `help(add_numbers)`, the text of the function's docstring is printed. The docstring thus helps a user better understand how to applying the function more effectively to their workflow.
-- When you build your package's documentation, the docstrings can be also used to automagically create full API documentation that provides a clean view of all its functions, methods, attributes, and classes.
+- When you call `help()` in Python, for example, `help(add_numbers)` will show the text of the function's docstring. The docstring thus helps a user better understand how to applying the function more effectively to their workflow.
+- When you build your package's documentation, the docstrings can also be used to automagically create full API documentation that provides a clean view of all its functions, classes, methods, and attributes.
 
 ```{tip}
-Example API Documentation for all functions, methods, attributes and classes in a package.
+Example API Documentation for all functions, classes, methods, and attributes in a package.
 * [View example high level API documentation for the Verde package. This page lists every function and class in the package along with a brief explanation of what it does](https://www.fatiando.org/verde/latest/api/index.html)
 * [You can further dig down to see what a specific function does within the package by clicking on an API element](https://www.fatiando.org/verde/latest/api/generated/verde.grid_coordinates.html#verde.grid_coordinates)
 ```
@@ -166,7 +166,7 @@ doctest adding another quality check to your package.
 <!-- This link isn't working no matter how i create the target. not sure
 why -->
 
-Above, we provided some examples of good, better, best docstring formats. If you are using Sphinx to create your docs, you can add the [doctest](https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html) extension to your Sphinx build. Doctest provides an additional; check for docstrings with example code in them.
+Above, we provided some examples of good, better, best docstring formats. If you are using Sphinx to create your docs, you can add the [doctest](https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html) extension to your Sphinx build. Doctest provides an additional check for docstrings with example code in them.
 Doctest runs the example code in your docstring `Examples` checking
 that the expected output is correct. Similar to running
 tutorials in your documentation, `doctest` can be a useful step that
@@ -186,29 +186,30 @@ 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.
+def add_me(num1, num2):
+    """A function that sums two numbers.
 
     Parameters
     ----------
-    aNum : int
-        An integer value to be printed
+    num1 : int
+        An integer value to be added
+    num2 : int
+        An integer value to be added
 
     Returns
     -------
-        Prints the integer that you provide the function.
+       The integer sum of the provided numbers.
 
     Examples
     --------
-    Below you can see how the `print_me` function will print a number that
-    you provide it.
+    Below you can see how the `add_me` function will return a number.
 
-    >>> add_me(1+3)
+    >>> add_me(1, 3)
     4
 
     """
 
-    return aNum + aNum2
+    return num1 + num2
 
 
 ```
@@ -219,13 +220,15 @@ In the example above, you saw the use of numpy-style docstrings to describe data
 that are passed into functions as parameters or
 into classes as attributes. In a numpy-style docstring you add those
 types in the Parameters section of the docstring. Below you can see that
-the parameter `aNum` should be a Python `int` (integer) value.
+the parameter `num1` and `num2` should both be a Python `int` (integer) value.
 
 ```python
     Parameters
     ----------
-    aNum : int
-        An integer value to be printed
+    num1 : int
+        An integer value to be added
+    num2 : int
+        An integer value to be added
 ```
 
 Describing the expected data type that a function or method requires
@@ -238,16 +241,16 @@ to get to know your code base quickly.
 Type hints are added to the definition of your function. In the example below, the parameters aNum and aNum2 are defined as being type = int (integer).
 
 ```python
-def add_me(aNum: int, aNum2: int):
-    """A function that prints a number that it is provided.
+def add_me(num1: int, num2: int):
+    """A function that sums two numbers.
 ```
 
 You can further describe the expected function output using `->`. Below
 the output of the function is also an int.
 
 ```python
-def add_me(aNum: int, aNum2: int) -> int:
-    """A function that prints a number that it is provided.
+def add_me(num1: int, num2: int) -> int:
+    """A function that sums two numbers.
 ```
 
 ### Why use type hints
diff --git a/documentation/write-user-documentation/get-started.md b/documentation/write-user-documentation/get-started.md
@@ -14,19 +14,19 @@ Your package:
 ## Core components of user-facing Python package documentation
 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)`.
+**User-facing documentation** refers to documentation that describes the way the
+tools within a package are broadly used in workflows. **API documentation** refers
+to documentation of functions, classes, methods, and attributes in your code and
+is written at a more granular level. This documentation is what 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 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
+* **Short Tutorials:** Your user-facing documentation should also include [**short tutorials** that showcase core features of your package](create-package-tutorials).
+* **Package Code / API documentation:** You package's functions, classes, methods, and attributes (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, classes, and methods in
 your Python package. [We discuss code documentation and docstrings in greater detail here.](document-your-code-api-docstrings)
 
 ### Write usable documentation
@@ -46,13 +46,13 @@ to a broader audience:
 ## Four elements of a good open source documentation landing page
 
 To make it easy for users to find what they need quickly,
-consider adding quick links on your packages landing
+consider adding quick links on your package's landing
 page to the following elements:
 
 * **Getting started:** This section should provide the user with a quick start for installing your package. A small example of how to use the package is good to have here as well. Or you can link to useful tutorials in the get started section.
 * **About:** Describe your project,  stating its goals and its functionality.
 * **Community:** Instructions for how to help and/or get involved. This might include links to your issues (if that is where you let users ask questions) or the discussion part of your GitHub repo. This section might include a development guide for those who might contribute to your package.
-* **API Documentation:** This is the detailed project documentation. Here you store documentation for your package's api including all user-facing functions, methods classes. And any additional high level discussion that will help people use your package.
+* **API Documentation:** This is the detailed project documentation. Here you store documentation for your package's API including all user-facing functions, classes, methods, and attributes as well as any additional high level discussion that will help people use your package.
 
 
 ```{figure} /images/geopandas-documentation-landing-page.png
