Fix: add tutorial and coc text and general cleanup

lwasser · lwasser · commit 0a02186941b4 · 2023-01-19T09:55:32.000-07:00
diff --git a/documentation/contributing-license-coc.md b/documentation/contributing-license-coc.md
@@ -81,9 +81,13 @@ 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.
 
-## Code of conducT
-
-contributors convenant...
+## 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 
+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.  
 
 <!-- 
 pyOpenSci packages must:
diff --git a/documentation/index.md b/documentation/index.md
@@ -1,5 +1,20 @@
 # Documentation for your Open Source Python Package - An Overview
 
+```{important}
+## Quick Takeaways: Documentation must haves
+
+Your package should at a minimum have:
+* README.MD file
+* CONTRIBUTING.md file
+* CODE_OF_CONDUCT.md 
+* LICENSE.txt 
+* User-facing documentation website with tutorials 
+* 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 
+tools that will help you build your documentation. 
+```
 
 ## Documentation is critical to the success of your Python open source package 
 
@@ -17,22 +32,20 @@ In the pyOpenSci open peer review process we look for several files and elements
 when evaluating package documentation, including:
 
 1. [A clear and to the point **README.md** file](readme-file-best-practices)
-1. **User oriented package documentation** that helps users understand how to install, use and cite your package. 
+1. [**User focused package documentation**](package-documentation-best-practices) that helps users understand how to install, use and cite your package. Documentation is most often contained in a stand-alone website. 
 1. **Tutorials and quick start code examples** that help a user get started using your package. 
-1. **Package API documentation.** Package API documentation refers to documentation for each class, function, method and user-facing attribute (*available for a user to see*) in your package. This means that your package methods and classes should have [thoughtful docstrings](https://pandas.pydata.org/docs/development/contributing_docstring.html) that describe both the purpose of the code element and each input and output. To help your users better understand how to use your package, you can include short code examples showing how to use the function or class in each docstring. If you don't know what API documentation means, this section of the pyOpenSci Python packaging guide is for you! 
-1. A **CONTRIBUTING.md** file 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.
-1. A **CODE_OF_CONDUCT.md** file.  
-1. **LICENSE.txt file & Citation instructions:** A license file and instructions for citing your package. 
-
-
+1. **Package API documentation.** Package API documentation refers to documentation for each class, function, method and user-facing attribute (*available for a user to see*) in your package. This means that your package methods and classes should have [thoughtful docstrings](https://pandas.pydata.org/docs/development/contributing_docstring.html) that describe both the purpose of the code element and each input and output.
+1. 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.
+ 1. 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> -->
+1. [**LICENSE.txt file & Citation instructions:**](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. 
 
 ```{figure} ../images/moving-pandas-python-package-github-main-repo.png
 ---
 name: directive-fig
 width: 80%
 alt: Image showing the files in the Moving Pandas GitHub repository. 
 ---
-An example 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)*
+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)*
 ```
 
 The above files are evaluated on many online platforms that track package health.
@@ -44,7 +57,7 @@ has in their GitHub repository.
 name: directive-fig
 width: 80%
 ---
-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 [moving pandas GitHub repo](https://github.com/anitagraser/movingpandas/community) *(screen shot taken Nov 23 2022)*
+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.
@@ -63,7 +76,7 @@ Screenshot showing [SNYK](https://snyk.io/advisor/python/movingpandas) package h
 ## What's next in this Python package documentation section?
 
 The rest of the pages in this section will walk you through best practices for setting up
-documentation for your Python package.
+documentation for your Python package. We will also suggest tools that you can use to build your user-facing documentation website.
 
 
 <!-- # TODO LINK TO CI BUILD examples FOR Documentation - we have plenty in our repos already for folks to look at. -->
diff --git a/documentation/package-documentation-best-practices.md b/documentation/package-documentation-best-practices.md
@@ -1,11 +1,23 @@
 # Best practices for writing user-facing documentation for your Python package 
 
+```{important}
+## Quick takeaways: best practices
+
+Your package: 
+* Should have a documentation website 
+* All of its functions and classes (the API) documented
+* Your package should use numpy-style docstrings 
+* Your documentation landing page should direct users to 4 core sections: get started, documentation content, about and community.
+* Documentation should include short quick-start tutorials
+```
+
 In addition to a well designed [README.md file](readme-file-best-practices), 
 and a [CONTRIBUTING.md file](contributing-file), 
 there are several core components of Python package documentation, 
 including:
 
 * **User-facing documentation website:** This refers to easy-to-read documentation that helps a user work with your package. This documentation should help users both install and use the functionality of your package.  
+    * Your user facing documentation should also include [short tutorials that show a user how to quickly get started using your package](python-package-documentation-tools.html#create-python-package-tutorials-that-both-help-users-and-test-your-package-s-code). If you use a tool such as sphinx-gallery or nbsphinx that runs the code in your tutorials, then these tutorials can also become an important part of your package's test suite.   
 * **API documentation:** The API refers to the functions and classes in a 
 package that makes up the user interface. API documentation is 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 
@@ -53,11 +65,20 @@ Below is an example of doing this using `myst` syntax.
 ````
 `````
 
-## API's and Docstrings
+## Create tutorials in your documentation 
+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. 
 
-### What is an API?
+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. 
 
-API standards for **A**pplied **P**rogramming **I**nterface. When 
+## Documenting the code in your package's API using docstrings
+
+### What is an API?
+API stands for **A**pplied **P**rogramming **I**nterface. When 
 discussed in the context of a (Python) package, the API refers to 
 the interface and tools that you, as a package user, use in a package. 
 
diff --git a/documentation/python-package-documentation-tools.md b/documentation/python-package-documentation-tools.md
@@ -10,13 +10,13 @@ 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. 
+* 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!*
 
 ```
 
 In addition to your:
-* [README.md file](readme-file-best-practices.md), 
-* [CONTRIBUTING.md and development guides and LICENSE file](contributing-file.md),
+* [README.md file](readme-file-best-practices), 
+* [CONTRIBUTING.md and development guides and LICENSE file](contributing-license-coc),
 
 you should also have user-facing documentation for your Python 
 package. Most often, user-facing documentation is contained on a hosted 
@@ -30,9 +30,9 @@ Here, we focus on tools and infrastructure that you can use.
 [Click here if you want to learn more about documentation best practices](package-documentation-best-practices.md).
 
 ```{note}
-Examples of documentation that we love:
+Examples of documentation websites that we love:
 
-* [geopandas](https://geopandas.org/en/stable/)
+* [GeoPandas](https://geopandas.org/en/stable/)
     * [View rst to create landing page](https://raw.githubusercontent.com/geopandas/geopandas/main/doc/source/index.rst)
 * [verde](https://www.fatiando.org/verde/latest/)
     * [View verde landing page code - rst file.](https://github.com/fatiando/verde/blob/main/doc/index.rst)
@@ -107,7 +107,7 @@ If you are on the fence about myST vs rst, you might find that **myST** is easie
 for more people to contribute to.  
 ```
 
-## Sphinx extensions to support python package tutorials 
+## Create python package 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. 
@@ -135,12 +135,34 @@ your documentation, the gallery extension:
 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
 
-<!-- TODO: Add thumbnails out tutorial outputs  -->
+
+```{figure} ../images/sphinx-gallery-overview.png
+---
+name: directive-fig
+width: 80%
+alt: Image showing the gallery output provided by sphinx-gallery where each tutorial is in a grid and the tutorial thumbnails are created from a graphic in the tutorial.
+---
+`sphinx-gallery` makes it easy to create a user-friendly tutorial gallery.
+Each tutorial has a download link where the user can download a **.py** file or a Jupyter Notebook. And it renders the tutorials in a user-friendly grid. 
+```
+
+Below you can see what a tutorial looks like created with sphinx-gallery.
+
+```{figure} ../images/sphinx-gallery-tutorial.png
+---
+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. 
+---
+`sphinx-gallery` tutorials by default include download links for both the 
+python script (**.py** file) and a Jupyter notebook (**.ipynb** file) at the bottom. 
+```
 
 ### Sphinx Gallery benefits 
 * 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 
+* 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 
 
@@ -157,13 +179,31 @@ 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 - 
+
+```bash 
+$ docs % make html 
+
+Sphinx-Gallery successfully executed 2 out of 2 files
+```
+File directory structure: 
+
 ```bash
 tutorials/
     index.rst # landing page for your gallery
-    tutorial.py # a tutorial 
-    plot_tutorial.py # a tutorial that produces a plot output
-tutorial_outputs/ 
-    add fils here... 
+    plot_tutorial.py # a tutorial 
+    plot_tutorial-2.py # a tutorial that produces a plot output
+_build/
+    build_examples/ # This is where the downloadable tutorial files live 
+        plot_sample-1.ipynb
+        plot_sample-1.py
+        ...
+    html/ 
+        built_examples/ # You can specify this dir name in gallery settings
+            index.html 
+            plot_sample-1.html 
+            plot_sample.html 
+            sg_execution_times.html # in case you want to see build times for each tutorial 
+
 ```
 
 ### [nbsphinx - tutorials using Jupyter Notebooks](https://nbsphinx.readthedocs.io/en/latest/)
@@ -193,8 +233,19 @@ tutorials/
     index.md # Landing page for your gallery
     tutorial.ipynb # A tutorial in a jupyter notebook
     another_tutorial.ipynb
-tutorial_outputs/ 
-    add fils here... 
-```
+# This shows you what the build directory looks like when you build with sphinx-build
+_build/
+    html/
+        # 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!
+        tutorials/ 
+            index.html
+            index.md 
+            plot_sample-2.html 
+            plot_sample-2.ipynb
+            ...
+``` 
 
 
diff --git a/images/sphinx-gallery-overview.png b/images/sphinx-gallery-overview.png
diff --git a/images/sphinx-gallery-tutorial.png b/images/sphinx-gallery-tutorial.png
diff --git a/index.md b/index.md
@@ -52,9 +52,10 @@ Learn about our open peer review process
 ✨ Documentation Criteria & Recommendations ✨
 ^^^
 
-Learn about the good, better and best practices 
-associated with Python package documentation. Topics 
-covered include: README files, tutorials and full docs. 
+Learn more about the best practices for Python package 
+documentation and also some of the tools for creating 
+documentation that are 
+commonly used in the scientific Python community. 
 :::
 
 :::{grid-item-card}
@@ -64,8 +65,9 @@ covered include: README files, tutorials and full docs.
 
 ✨ Package Structure & Code ✨
 ^^^
-<!-- 
-Get a basic overview of our open peer review process for Python scientific open source software. -->
+Under Construction - Coming Spring 2023! 
+Learn more about standards for packaging structure and 
+builds in the scientific Python community. 
 :::
 
 :::{grid-item-card}
@@ -112,11 +114,11 @@ to see here, [we invite you to open an issue on GitHub that details any changes
 :caption: Documentation
 
 Documentation Overview <documentation/index>
-Package Documentation Best Practices <documentation/package-documentation-best-practices>
-Package Documentation Tools <documentation/python-package-documentation-tools>
+Best Practices for Docs <documentation/package-documentation-best-practices>
+Tools to Build Your Docs <documentation/python-package-documentation-tools>
 Host & Help People Find Your Docs <documentation/website-hosting-optimizing-your-docs>
 The README File <documentation/readme-file-best-practices.md>
-Contributing & License files <documentation/contributing-file>
+Contributing & License files <documentation/contributing-license-coc>
 ```
 
 ```{toctree}
