Some more changes (#167)

* Jupyter Notebooks: fix typos; fix broken plot * Update discussion of IDEs and improve formatting * Recommend PyLance extension instead of pyright. Closes #162 * update changelog and copyright date * add discussion board link * one line per sentence * Update Python/Module1_GettingStartedWithPython/Getting_Started_With_IDEs_and_Notebooks.md Co-authored-by: Petar Griggs <petargriggs@gmail.com> * Update Python/Module1_GettingStartedWithPython/Getting_Started_With_IDEs_and_Notebooks.md Co-authored-by: Petar Griggs <petargriggs@gmail.com> * Update Python/Module1_GettingStartedWithPython/Getting_Started_With_IDEs_and_Notebooks.md Co-authored-by: Petar Griggs <petargriggs@gmail.com> * Update Python/Module1_GettingStartedWithPython/Getting_Started_With_IDEs_and_Notebooks.md Co-authored-by: Petar Griggs <petargriggs@gmail.com> * Update Python/Module1_GettingStartedWithPython/Getting_Started_With_IDEs_and_Notebooks.md Co-authored-by: Petar Griggs <petargriggs@gmail.com> * Update Python/Module5_OddsAndEnds/Writing_Good_Code.md Co-authored-by: Petar Griggs <petargriggs@gmail.com> * Update Python/Module1_GettingStartedWithPython/Getting_Started_With_IDEs_and_Notebooks.md Co-authored-by: Petar Griggs <petargriggs@gmail.com> Co-authored-by: Petar Griggs <petargriggs@gmail.com>

Author: rsokl

Python/Module1_GettingStartedWithPython/Getting_Started_With_IDEs_and_Notebooks.md

@@ -39,39 +39,49 @@ First and foremost, a good IDE will provide a text editor that will:
 
 An IDE also often provides debugging tools so that you can test your code; it will also typically interface with version-control software, like Git, so that you can keep track of versions of your code as you modify it. We will not discuss these useful, but more advanced features here.
 
-### Recommended IDEs
+## Recommended IDEs
 There are many excellent IDEs that can be configured to work well with Python. Two IDEs that we endorse are:
 
-[PyCharm](https://www.jetbrains.com/pycharm/download): A powerful IDE dedicated to Python.
+### PyCharm
+
+[PyCharm](https://www.jetbrains.com/pycharm/download) is a powerful and highly-polished IDE dedicated to developing Python code.
 
 **Pros**
 
-- works well out-of-the-box
-- long-supported by professionals and thus is very reliable
-- highly configurable
-- fully-featured, with an excellent debugger, context-dependent "intellisense", type-inference, and more
-- the free "community version" is extremely robust and feature-rich. 
+- Works well out-of-the-box.
+- Long-supported by professionals and thus is very reliable.
+- Highly configurable.
+- Fully-featured, with an excellent debugger, context-dependent "intellisense", type-inference, and more.
+- The free "community version" is extremely robust and feature-rich.
+- Generally provides an extremely high-quality and responsive experience for doing Python development.
 
 **Cons**
 
- - can be resource-heavy, especially for a laptop
- - may be overwhelming to new users (but has good documentation and tutorials)
- - Jupyter notebook support requires the premium version of PyCharm, making it inaccessible to newcomers
+ - Can be resource-heavy, especially for a laptop.
+ - May be overwhelming to new users (but has good documentation and tutorials).
+ - Jupyter notebook support requires the premium version of PyCharm, making it inaccessible to newcomers.
 
-[Visual Studio Code](https://code.visualstudio.com/) with the [Python extension](https://code.visualstudio.com/docs/languages/python): A lightweight, highly customizable IDE.
+### Visual Studio Code
+
+[Visual Studio Code](https://code.visualstudio.com/) (with the [Python extension](https://code.visualstudio.com/docs/languages/python)) is a lightweight, highly customizable IDE that works with many different languages.
+
+Note: if you decide to use VSCode to do Python development, it is highly recommended that you install Microsoft's [PyLance](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance)
+extension.
+This adds many useful features to the IDE that will make writing Python code a more delightful experience. 
 
 **Pros**
 
-- lightweight and elegant
-- completely free
-- works with many different languages, so you only need to familiarize yourself with one IDE if you are a polyglot programmer
-- a huge number of extensions can be downloaded to add functionality to the editor; these are created by a large community of open-source developers.
-- [has native support for Jupyter notebooks](https://code.visualstudio.com/docs/python/jupyter-support), meaning that you get VSCode's intellisense, debugger, and ability to inspect variables, all in a notebook.
+- Lightweight and elegant.
+- Completely free.
+- Works with many different languages, so you only need to familiarize yourself with one IDE if you are a polyglot programmer.
+- Offers a huge number of extensions that can be downloaded to add functionality to the editor; these are created by a large community of open-source developers.
+- [Has native support for Jupyter notebooks](https://code.visualstudio.com/docs/python/jupyter-support), meaning that you get VSCode's intellisense, debugger, and ability to inspect variables, all in a notebook.
+- Provides incredibly robust [remote coding](https://code.visualstudio.com/docs/remote/remote-overview) and [collaborative coding](https://visualstudio.microsoft.com/services/live-share/) capabilities.
 
 **Cons**
 
-- configuring VSCode for python development can have a moderate learning curve for newcomers
-- many features, like context-aware intellisense and type-inference, are simply more polished and powerful in PyCharm
+- Configuring VSCode for Python development can have a moderate learning curve for newcomers.
+- Some features, like context-aware intellisense and type-inference, are simply more polished and powerful in PyCharm.
 
 
 <div class="alert alert-info">

Python/Module1_GettingStartedWithPython/Jupyter_Notebooks.md

@@ -52,19 +52,24 @@ You should be all set once you have followed the prompts and the installation ha
 Note that you will need to repeat this process if you [create a new conda environment](https://www.pythonlikeyoumeanit.com/Module1_GettingStartedWithPython/Installing_Python.html#A-Brief-Introduction-to-Conda-Environments) with IPython/Jupter installed in it.
 </div>
 
-In recent years, the Jupyter Notebook has become a massively popular tool for doing research-oriented work in Python and other languages alike. Its emergence marked a paradigm shift in the way data science is conducted. 
+In recent years, the Jupyter Notebook has become a massively popular tool for doing research-oriented work in Python and other languages alike.
+Its emergence marked a paradigm shift in the way data science is conducted. 
 
-A Jupyter notebook is similar to the IPython console, but, instead of only being able to work with a single line of code at a time, you can easily edit and re-execute *any* code that had been written in a notebook. Furthermore, you can save a notebook, and thus return to it later. Additionally, a notebook provides many terrific features. For instance, you can embed visualizations of data within a notebook, and write blocks of nicely-formatted text (using the [Markdown syntax](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)), for presenting and explaining the contents of the notebook. 
+A Jupyter notebook is similar to the IPython console, but, instead of only being able to work with a single line of code at a time, you can easily edit and re-execute *any* code that had been written in a notebook. Furthermore, you can save a notebook, and thus return to it later.
+Additionally, a notebook provides many terrific features. For instance, you can embed visualizations of data within a notebook, and write blocks of nicely-formatted text (using the [Markdown syntax](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)), for presenting and explaining the contents of the notebook. 
 
 In this way, the Jupyter Notebook stands out as an excellent tool for many practical applications. You could work on a notebook while you are working through sections of this website, for instance, testing out snippets of code, and answering reading-comprehension questions as you proceed through the text, and using markdown-headers to visually separate different portions of the notebook. When I do research, I am always creating Jupyter notebooks in which I write code that analyzes data, I plot various results, presented in different ways, and I write detailed markdown-text blocks to document my work. The end result is something that I can share with my labmates, and easily revisit months later without having to struggle to recall what I had done.
 
 ## Jupyter Lab
-[Jupyter lab](https://jupyterlab.readthedocs.io/) is a new web interface from Project Jupyter that provides a rich web-based interface for managing and running Jupyter notebooks, console terminals, and text editors, all within your browser. Among its useful features and polished user interface - compared to that a Jupyter notebook server - Jupyter lab provides moveable panes for viewing data, images, and code output apart from the rest of the notebook. This is facilitates effective data science work flows.
+[Jupyter lab](https://jupyterlab.readthedocs.io/) is a new web interface from Project Jupyter that provides a rich web-based interface for managing and running Jupyter notebooks, console terminals, and text editors, all within your browser.
+Among its useful features and polished user interface, Jupyter lab provides moveable panes for viewing data, images, and code output apart from the rest of the notebook.
+This is facilitates effective data science work flows.
 
 It is recommended that you peruse the [Jupyter lab documentation](https://jupyterlab.readthedocs.io/en/stable/getting_started/overview.html) to get a feel for all of its added capabilities.
 
 
-The following instructions are laid out for running a Jupyter notebook server. That being said, the process for running a Jupyter lab server and working with notebooks therein is nearly identical. Both Jupyter notebook and Jupyter lab should already be [installed via Anaconda](https://www.pythonlikeyoumeanit.com/Module1_GettingStartedWithPython/Installing_Python.html).
+The following instructions are laid out for running a Jupyter notebook server. That being said, the process for running a Jupyter lab server and working with notebooks therein is nearly identical.
+Both Jupyter notebook and Jupyter lab should already be [installed via Anaconda](https://www.pythonlikeyoumeanit.com/Module1_GettingStartedWithPython/Installing_Python.html).
 
 
 ## Running a Notebook Server & Creating a Notebook
@@ -133,7 +138,7 @@ import numpy as np
 import matplotlib.pyplot as plt
 
 # this tells Jupyter to embed matplotlib plots in the notebook
-%matplotlib notebook 
+%matplotlib inline 
 ```
 
 ```python

Python/Module5_OddsAndEnds/Writing_Good_Code.md

@@ -440,7 +440,10 @@ This saves us the trouble of having to run our code, hit an error, read through
 
 It does not take long to experience the benefits of type-hinting through your IDE. This both accelerates your coding by informing you of the object types that you are working with on the fly, and helps to expose oversights in your code as soon as they are made. 
 
-Finally, it is also worthwhile to highlight two projects, [mypy](http://mypy-lang.org/) and [pyright](https://github.com/microsoft/pyright), which are used to perform static type-checking on your code based on your type-hints. That is, mypy and pyright will both automatically traverse your code and find potential bugs by identifying type conflicts in your code (e.g. trying to capitalize an integer) by checking their annotated and inferred types. These tools are especially useful for large-scale code bases. Companies like Dropbox and Microsoft make keen use of static type-checking to identify inconsistencies in their code without having to hit runtime errors. Keep mypy, pyright, and other type-checking utilities in mind as you mature as a Python developer and find yourself working on projects of growing complexity. If you are using [VSCode as your IDE](https://www.pythonlikeyoumeanit.com/Module1_GettingStartedWithPython/Getting_Started_With_IDEs_and_Notebooks.html), you can install the [pyright vscode extension](https://marketplace.visualstudio.com/items?itemName=ms-pyright.pyright) to leverage type checking within your IDE.
+Finally, it is also worthwhile to highlight two projects, [mypy](http://mypy-lang.org/) and [pyright](https://github.com/microsoft/pyright), which are used to perform static type-checking on your code based on your type-hints.
+That is, mypy and pyright will both automatically traverse your code and find potential bugs by identifying type conflicts in your code (e.g. trying to capitalize an integer) by checking their annotated and inferred types.
+These tools are especially useful for large-scale code bases. Companies like Dropbox and Microsoft make keen use of static type-checking to identify inconsistencies in their code without having to hit runtime errors. Keep mypy, pyright, and other type-checking utilities in mind as you mature as a Python developer and find yourself working on projects of growing complexity.
+If you are using [VSCode as your IDE](https://www.pythonlikeyoumeanit.com/Module1_GettingStartedWithPython/Getting_Started_With_IDEs_and_Notebooks.html), you can install the [PyLance VSCode extension](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance) to leverage pyright's type checking within your IDE.
 <!-- #endregion -->
 
 <div class="alert alert-info">

Python/changes.rst

@@ -5,11 +5,29 @@ Changelog
 This is a record of all past PLYMI releases and what went into them,
 in reverse chronological order.
 
+
+----------
+2021-01-30
+----------
+
+Updated the discussion of `computing pairwise differences <https://www.pythonlikeyoumeanit.com/Module3_IntroducingNumpy/Broadcasting.html#An-Advanced-Application-of-Broadcasting:-Pairwise-Distances>`_
+to account for potential floating-point edge cases that can produce "NaNs" as a result.
+
+There is currently an incompatibility between `jedi 0.18.0` and IPython, which breaks autocompletion. See `here <https://github.com/ipython/ipython/issues/12740>`_ for more details.
+Added temporary callout boxes to the `informal introduction to Python <https://www.pythonlikeyoumeanit.com/Module1_GettingStartedWithPython/Informal_Intro_Python.html>`_ and to
+the `introduction to Jupyter notebooks <https://www.pythonlikeyoumeanit.com/Module1_GettingStartedWithPython/Jupyter_Notebooks.html>`_, which instruct readers to remedy this by downgrading jedi.
+
+Fixed a missing plot in the `introduction to Jupyter <https://www.pythonlikeyoumeanit.com/Module1_GettingStartedWithPython/Jupyter_Notebooks.html>`_ section.
+
+Reformatted the `section on IDEs <https://www.pythonlikeyoumeanit.com/Module1_GettingStartedWithPython/Getting_Started_With_IDEs_and_Notebooks.html>`_ and added a description of PyLance.
+
+Add link to `PLYMI's discussion board <https://github.com/rsokl/Learning_Python/discussions>`_.
+
 ----------
 2021-01-24
 ----------
 
-Added brief discussion on semantic versioning. Thanks `@samaocarpenter <https://github.com/samaocarpenter>`_!
+Added a brief `discussion of Python versions <https://www.pythonlikeyoumeanit.com/Module1_GettingStartedWithPython/GettingStartedWithPython.html#Understanding-Different-Versions-of-Python>`_. Thanks `@samaocarpenter <https://github.com/samaocarpenter>`_!
 
 Fixed typos `#160 <https://github.com/rsokl/Learning_Python/pull/160>`_ `#158 <https://github.com/rsokl/Learning_Python/pull/158>`_
 `#155 <https://github.com/rsokl/Learning_Python/pull/155>`_

Python/conf.py

@@ -59,7 +59,7 @@
 
 # General information about the project.
 project = "Python Like You Mean It"
-copyright = "2019, Ryan Soklaski"
+copyright = "2021, Ryan Soklaski"
 author = "Ryan Soklaski"
 html_title = "Python Like You Mean It"
 

Python/index.rst

@@ -12,7 +12,7 @@ What this is
 ------------
 Python Like You Mean It (PLYMI) is a free resource for learning the basics of Python & NumPy, and moreover, becoming a competent Python user. The features of the Python language that are emphasized here were chosen to help those who are particularly interested in STEM applications (data analysis, machine learning, numerical work, etc.).
 
-I want this to be a lean, one-stop resource for learning the essentials of Python from scratch. The reader will begin by learning about what Python is and what installing Python even means, and will hopefully walk away with a solid understanding of a substantial core of the language and its premiere numerical library, NumPy. I am also placing an emphasis on best practices throughout this site and am teaching to the latest version of Python (version 3.8, as of writing this).
+I want this to be a lean, one-stop resource for learning the essentials of Python from scratch. The reader will begin by learning about what Python is and what installing Python even means, and will hopefully walk away with a solid understanding of a substantial core of the language and its premiere numerical library, NumPy. I am also placing an emphasis on best practices throughout this site and am teaching to the latest version of Python (version 3.9, as of writing this).
 
 
 What this isn't
@@ -32,10 +32,18 @@ Python shouldn't be *too* easy
 Python is a relatively easy language to pick up, and it doesn't require much rigor to make code work. Unfortunately, this means that there are many Python users out there who know enough to just get by, but lack a sound understanding of the language. You don't want to get caught in the "know enough Python to be dangerous" zone; therein lies complacency, stagnation, and the genesis of a lot of bad code. You've got to Python like you mean it!
 
 
+Join Our Discussion Board
+-------------------------
+`Join the PLYMI community <https://github.com/rsokl/Learning_Python/discussions>`_ to ask questions, recommend new content, or to just say hello!
+
+(A note to `BWSI students <https://beaverworks.ll.mit.edu/CMS/bw/bwsi>`_: please stick to your class' piazza board for posting questions)
+
+
 PLYMI is on GitHub
 ------------------
 If you have questions about the reading, think that you have spotted some mistakes, or would like to contribute to PLYMI, please visit `our GitHub page <https://github.com/rsokl/Learning_Python>`_. You will need to create a GitHub account in order to post an issue; this process is free and easy. We would love for you to join us to discuss the website!
 
+
 Contributors
 ------------
 The following people made significant contributions to PLYMI, adding problems with worked solutions and valuable feedback on the text:

Python/intro.rst

@@ -12,7 +12,7 @@ What this is
 ------------
 Python Like You Mean It (PLYMI) is a free resource for learning the basics of Python & NumPy, and moreover, becoming a competent Python user. The features of the Python language that are emphasized here were chosen to help those who are particularly interested in STEM applications (data analysis, machine learning, numerical work, etc.).
 
-I want this to be a lean, one-stop resource for learning the essentials of Python from scratch. The reader will begin by learning about what Python is and what installing Python even means, and will hopefully walk away with a solid understanding of a substantial core of the language and its premiere numerical library, NumPy. I am also placing an emphasis on best practices throughout this site and am teaching to the latest version of Python (version 3.8, as of writing this).
+I want this to be a lean, one-stop resource for learning the essentials of Python from scratch. The reader will begin by learning about what Python is and what installing Python even means, and will hopefully walk away with a solid understanding of a substantial core of the language and its premiere numerical library, NumPy. I am also placing an emphasis on best practices throughout this site and am teaching to the latest version of Python (version 3.9, as of writing this).
 
 
 What this isn't
@@ -31,6 +31,12 @@ Python shouldn't be *too* easy
 ------------------------------
 Python is a relatively easy language to pick up, and it doesn't require much rigor to make code work. Unfortunately, this means that there are many Python users out there who know enough to just get by, but lack a sound understanding of the language. You don't want to get caught in the "know enough Python to be dangerous" zone; therein lies complacency, stagnation, and the genesis of a lot of bad code. You've got to Python like you mean it!
 
+Join Our Discussion Board
+-------------------------
+`Join the PLYMI community <https://github.com/rsokl/Learning_Python/discussions>`_ to ask questions, recommend new content, or to just say hello!
+
+(A note to `BWSI students <https://beaverworks.ll.mit.edu/CMS/bw/bwsi>`_: please stick to your class' piazza board for posting questions)
+
 
 PLYMI is on GitHub
 ------------------