Merge pull request #130 from MolSSI-Education/2023-review

This PR contains changes from the 2023 MolSSI CookieCutter/Best Practices sprint.

Changes:

* Episodes edited for clarity and grammatical correctness.
* Theme updated
* Starting code updated for newer versions of Python and NumPy
* Recommended Python version changed to 3.11
* GitHub Actions, CookieCutter information updated
* Starting/stopping repos added for each lesson.
* Docker container with molssi_best_practices environment added.

_episodes/00-code-organization-documentation.rst

@@ -1,9 +1,18 @@
 Code Style and Documentation
 ----------------------------
 
+Code style and documentation are topics that are often overlooked in a software project.
+However, these are important aspects of a project that can make it easier to maintain and extend.
+
+In this section, we will discuss some of the best practices for code style and documentation.
+
+.. csv-table:: 
+  :file: csv_tables/documentation.csv
+  :header-rows: 1
+
 .. toctree::
    :maxdepth: 1
-   :titlesonly:
+   :hidden:
 
    04-function-style
    05-package-structure

_episodes/00-git-and-github.rst

@@ -1,9 +1,22 @@
 git and GitHub
 -----------------
+Version control is a system that records changes to a file or set of files over time so that you can view or use specific versions later. 
+It is a fundamental tool in modern software development, and we recommend always using version control on your projects, even if you are working alone.
+Version control also facilitates collaboration between multiple people working on the same project.
+The most popular version control system is git, and you should have it set up on your comptuer from the set up section.
+
+Git projects (or repositories) can be hosted on a variety of platforms, but the most popular is GitHub.
+GitHub is a web-based hosting service for git repositories, and it provides a number of tools for software development.
+
+This section covers the basics of version control using git and sharing and collaborating on code using GitHub.
+
+.. csv-table:: 
+  :file: csv_tables/git_and_github.csv
+  :header-rows: 1
 
 .. toctree::
    :maxdepth: 1
-   :titlesonly:
+   :hidden:
 
    02-git
    03-github

_episodes/00-setup.rst

@@ -0,0 +1,23 @@
+Set-Up
+------
+
+This section covers the set-up necessary for the workshop.
+In the first lesson, you will learn how to set up your computer for Python development,
+including setting up the version control software, git, creating an account on the web platform GitHub,
+and installing and using the conda package manager.
+
+The second lesson will teach you how to create a Python package
+using the MolSSI Cookiecutter for computational molecular sciences.
+The MolSSI CMS Cookiecutter will create a skeletal Python package
+and files for testing, documentation, and continuous integration.
+
+.. csv-table:: 
+  :file: csv_tables/setup.csv
+  :header-rows: 1
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   setup
+   01-package-setup

_episodes/00-testing-continuous-integration.rst

@@ -1,9 +1,14 @@
 Testing, Continuous Integration, and Distribution
 -----------------------------------------------
+This section covers the testing, continuous integration, and distribution of software packages.
+
+.. csv-table:: 
+  :file: csv_tables/ci_testing.csv
+  :header-rows: 1
 
 .. toctree::
    :maxdepth: 1
-   :titlesonly:
+   :hidden:
 
    08-testing
    09-CI

_episodes/01-package-setup.md

@@ -19,10 +19,10 @@ Objectives:
 
 For this workshop,
 we are going to create a Python package that performs analysis and creates visualizations for molecules.
-We will start from a Jupyter notebook that has some functions and analysis.
-(You should have downloaded the Jupyter notebook during setup(setup).
+We will start with a Jupyter Notebook that has some functions and analysis.
+(You should have downloaded the Jupyter Notebook during setup ([Set Up](setup.md)). 
 
-The idea is that we would like to take this Jupyter notebook
+The idea is that we would like to take this Jupyter Notebook
 and convert the functions we have created into a Python package.
 That way, if anyone (a lab-mate, for example) would like to use our functions,
 they can do so by installing the package and importing it into their own scripts.
@@ -44,11 +44,11 @@ We will discuss what all of these are later in the workshop.
 
 ### Obtaining CookieCutter
 
-You should have the general CookieCutter installed, according to the directions given in the setup(setup) portion of this workshop.
-If you do not, please navigate to setup(setup) and follow the instructions given there.
+You should have the general CookieCutter installed, according to the directions given in the setup ([Set Up](setup.md)) portion of this workshop.
+If you do not, please navigate to setup ([Set Up](setup.md)) and follow the instructions given there.
 
 ### Running CookieCutter
-Navigate to the `molssi_best_practices` directory created during setup(setup).
+Navigate to the `molssi_best_practices` directory created during setup ([Set Up](setup.md)).
 (CookieCutter will generate the new project in a subdirectory.)
 Run the [CMS CookieCutter](https://github.com/MolSSI/cookiecutter-cms) to start your project:
 
@@ -59,13 +59,27 @@ Run the [CMS CookieCutter](https://github.com/MolSSI/cookiecutter-cms) to start
 ```
 ````
 
-
 This command runs the cookiecutter software (`cookiecutter` in the command)
 and tells cookiecutter to look at GitHub (`gh`) in the repository under `molssi/cookiecutter-cms`.
 This repository contains a template that cookiecutter uses to create your project,
 once you have provided some starting information.
 
-You will see an interactive prompt which asks questions about your project.
+
+:::{admonition} Cookiecutter Template Location
+:class: tip
+
+When we use the command `cookiecutter gh:molssi/cookiecutter-cms`, 
+we are using the Cookiecutter tool and telling it to use the GitHub repository `https://github.com/molssi/cookiecutter-cms` as a template.
+
+The `gh` is for GitHub, and the `molssi/cookiecutter-cms` is the repository name.
+
+You could point to any location where there is a Cookiecutter template,
+including files on your local file system or other online repositories.
+
+:::
+
+
+You will see an interactive prompt that asks questions about your project.
 Here, the prompt appears first, followed by the default value in square brackets.
 The first question will be on your project name.
 You have very cleverly decided to give it the name `molecool`
@@ -92,7 +106,7 @@ Select open_source_license:
 Choose from 1, 2, 3, 4 (1, 2, 3, 4) [1]: 2
 
 Select dependency_source:
-1 - Prefer conda-forge over the default anaconda channel with pip fallback
+1 - Prefer conda-forge with pip fallback
 2 - Prefer default anaconda channel with pip fallback
 3 - Dependencies from pip only (no conda)
 
@@ -109,12 +123,12 @@ Choose from 1, 2 (1, 2) [1]:
 ### Explanation of CookieCutter Questions
 
 The first two questions are for the project and repository name.
-The project name is the name of the project, while the repo name is the name of the folder that cookiecutter will create. Usually, you will leave these two to be the same thing.
-The `repo_name` is the name which you will use to import the package you eventually create, and because of that has some rules.
+The project name is the name of the project, while the repo name is the name of the folder that CookieCutter will create. Usually, you will leave these two to be the same thing.
+The `repo_name` is the name that you will use to import the package you eventually create, and because of that has some rules.
 The `repo_name` must be a valid Python module name and cannot contain spaces.
 
 The next choice is about the first module name.
-Modules are the `.py` files which contain python code.
+Modules are the `.py` files that contain Python code.
 The default for this is the `repo_name`, but we will change this to avoid confusion (the module `molecool.py` in a folder named `molecool` in a folder named `molecool`??).
 For now, we'll just name our first module `functions`, and this is where we will put all of our starting functions.
 
@@ -126,8 +140,8 @@ Note that your email address is not recorded or kept by the CookieCutter softwar
 
 #### License Choice
 Choosing which license to use is often confusing for new developers.
-The MIT license (option 1) is a very common license, and the default on GitHub.
-It allows for anyone to use, modify, or redistribute your work with no restrictions (and also no warranty).
+The MIT license (option 1) is a very common license and the default on GitHub.
+It allows anyone to use, modify, or redistribute your work with no restrictions (and also no warranty).
 
 Here, we have chosen the `BSD-3-Clause`.
 The `BSD-3-Clause` license is an open-source, permissive license (meaning that few requirements are placed on developers of derivative works), similar to the MIT license.
@@ -151,16 +165,16 @@ So, if you ever start a project that becomes popular or has contributors, be sur
 
  Open-source licenses can either be 'permissive' or 'copy-left'.
  Copy-left licenses require that derivative works also be open source.
- Out of the choices given above, MIT and BSD-3-Clause are permissive, while LGPLv3 is a copy left license.
+ Out of the choices given above, MIT and BSD-3-Clause are permissive, while LGPLv3 is a copyleft license.
 
  We recommend that you spend some time reading about licensing.
  One place to start is this [helpful guide]( https://github.com/choderalab/software-development/blob/master/LICENSING_GUIDELINES.md) from the Chodera Lab or the website [choosealicense.com](https://choosealicense.com).  
 ```
 
 #### Dependency Source
-This determines some things in set-up for what will be used to install dependencies for testing.
-This mostly has consequence for the section on [Continuous Integration](../08-CI/index.html).
-We have chosen to install dependencies from anaconda with pip fallback.
+This determines some things in the setup for what will be used to install dependencies for testing.
+This mostly has consequences for the section on [Continuous Integration](../08-CI/index.html).
+We have chosen to install dependencies from Anaconda with pip fallback.
 Don't worry too much about this choice for now.
 
 #### Support for ReadTheDocs
@@ -169,16 +183,24 @@ This option is to choose whether you would like files associated with the docume
 Choose "yes" for this workshop.
 
 ### Reviewing directory contents
-Now we can examine the project layout the CookieCutter has set up for us.
+Now we can examine the project layout CookieCutter has set up for us.
 Navigate to the newly created `molecool` directory.
+
+````{tab-set-code} 
+
+```{code-block} shell   
+cd molecool
+```
+````
+
 You should see the following directory structure.
 
 ```
 .
 ├── CODE_OF_CONDUCT.md              <- Code of Conduct for developers and users
 ├── LICENSE                         <- License file
 ├── MANIFEST.in                     <- Packaging information for pip
-├── README.md                       <- Description of project which GitHub will render
+├── README.md                       <- Description of the project which GitHub will render
 ├── molecool                        <- Basic Python Package import file
 │   ├── __init__.py                 <- Basic Python Package import file
 │   ├── functions.py                <- Starting package module
@@ -192,8 +214,6 @@ You should see the following directory structure.
 │   ├── README.md
 │   ├── conda-envs                  <- Conda environments for testing
 │   │   └── test_env.yaml
-│   ├── legacy-miniconda-setup      <- Legacy Travis CI Helper, will likely be removed in later version
-│   │   └── before_install.sh
 │   └── scripts
 │       └── create_conda_env.py     <- OS agnostic Helper script to make conda environments based on simple flags
 ├── docs                            <- Documentation template folder with many settings already filled in
@@ -208,29 +228,43 @@ You should see the following directory structure.
 │   ├── getting_started.rst
 │   ├── index.rst
 │   ├── make.bat
-│   └── requirements.yaml           <- Documenation building specific requirements. Usually a smaller set than the main program
+│   └── requirements.yaml           <- Documentation building specific requirements. Usually a smaller set than the main program
 ├── pyproject.toml                  <- Generic Python build system configuration (PEP-517).
 ├── readthedocs.yml
 ├── setup.cfg                       <- Near-master config file to make house INI-like settings for Coverage, Flake8, YAPF, etc.
-├── setup.py                        <- Your package's setup file for installing with additional options that can be set
+├── setup.py                        <- Your package's setup file for installation with additional options that can be set
 ├── .codecov.yml                    <- Codecov config to help reduce its verbosity to more reasonable levels
-├── .github                         <- GitHub hooks for user contribution, pull request guides and GitHub Actions CI
+├── .github                         <- GitHub hooks for user contribution, pull request guides, and GitHub Actions CI
 │   ├── CONTRIBUTING.md
 │   ├── PULL_REQUEST_TEMPLATE.md
 │   └── workflows
 │       └── CI.yaml
 ├── .gitignore                      <- Stock helper file telling git what file name patterns to ignore when adding files
 └── .lgtm.yml
 ```
+```{admonition} Visualizing the Directory Structure
+:class: note
 
 To visualize your project like above you will use `tree`.
 If you do not have `tree`, you can get it using `sudo apt-get install tree` on Linux,
 or `brew install tree` on Mac.
 Note: `tree` will not show you the helpful labels after `<-` (those were added by us).
+```
 
 CookieCutter has created a lot of files!
-They can be thought of as three sections.
-In the top level of our project we have a folder for tools related to development (`devtools`),
+
+If you have set up VSCode as your text editor as described in the setup ([Set Up](setup.md)), you can open a VSCode project that contains the newly created `molecool` directory by typing
+
+````{tab-set-code} 
+
+```{code-block} shell
+code .
+```
+````
+This will open a new VSCode window with your current directory (`.`) the `molecool` directory as the root directory.
+
+The files that Cookiecutter has created for us can be thought of as three sections.
+In the top level of our project, we have a folder for tools related to development (`devtools`),
 documentation (`docs`) and to the package itself (`molecool`).
 We will first be working in the `molecool` folder to build our package, and adding more things later.
 
@@ -271,15 +305,8 @@ To read more about Python packages vs. modules, check out [Python's documentatio
 ```
 
 ## The `molecool` directory
-Navigate inside our package directory. From the directory where you ran CookieCutter,
-
-````{tab-set-code} 
-
-```{code-block} shell
- cd molecool
-```
-````
-
+We will first examine some files in the `molecool` directory.
+This is the directory that contains our package code.
 
 ### The `__init__.py` file
 
@@ -383,7 +410,7 @@ Open Python (type `python` into your terminal window), and type
 
 
 This will give a list of locations python looks for packages when you do an import.
-One of the locations should end with `python3.7/site-packages`.
+One of the locations should end with `python3.11/site-packages`.
 The site packages folder is where all of your installed packages for a particular environment are located.
 
 To do a development mode install, type
@@ -444,11 +471,21 @@ If you are in the project directory, the code will still work. However, it will
 
 ````
 
+:::{admonition} Final Repository State
+:class: tip
+
+You can see the final state of the repository after this section [here](https://github.com/MolSSI-Education/molecool/tree/e703f52e9381b051415264927d2bde6c1cebb52a).
+
+You can also download a zip of the repository [here](https://github.com/MolSSI-Education/molecool/archive/refs/tags/cookiecutter-end.zip).
+
+:::
+
+
 ## Key Points
 
 ```{admonition} Key Points
 :class: key
 
 * There is a common way to structure Python packages.
 * You can use the CMS CookieCutter to quickly create the layout for a Python package.
-```
+```