adopt myst

run rst2myst, with minimal manual formatting fixes

docs/contributing/packages.md

@@ -0,0 +1,40 @@
+(contributing-packages)=
+
+# Environments & Packages
+
+TLJH installs packages from different sources during installation.
+This document describes the various sources and how to upgrade
+versions of packages installed.
+
+## Python Environments
+
+TLJH sets up two python environments during installation.
+
+1. **Hub Environment**. JupyterHub, authenticators, spawners, TLJH plugins
+   and the TLJH configuration management code is installed into this
+   environment. A [venv](https://docs.python.org/3/library/venv.html) is used,
+   primarily since conda does not support ARM CPUs and we'd like to support the
+   RaspberryPI someday. Admins generally do not install custom packages
+   in this environment.
+2. **User Environment**. Jupyter Notebook, JupyterLab, nteract, kernels,
+   and packages the users wanna use (such as numpy, scipy, etc) are installed
+   here. A [conda](https://conda.io) environment is used here, since
+   a lot of scientific packages are available from Conda. `pip` is still
+   used to install Jupyter specific packages, primarily because most notebook
+   extensions are still available only on [PyPI](https://pypi.org).
+   Admins can install packages here for use by all users.
+
+## Python package versions
+
+In `installer.py`, most Python packages have a version specified. This
+can be upgraded freely whenever needed. Some of them have version checks
+in `integration-tests/test_extensions.py`, so those might need
+updating too.
+
+## Apt packages
+
+Base operating system packages, including Python itself, are installed
+via `apt` from the base Ubuntu repositories.
+
+We generally do not pin versions of packages provided by apt, instead
+just using the latest versions provided by Ubuntu.