Add documentation of pyproject.toml (#30)

Author: jorgensd

Dockerfile

@@ -1,22 +1,26 @@
-# We create a simple docker file that install the necesseary dependencies for the package
+# We choose ubuntu 22.04 as our base docker image
 
 FROM ubuntu:22.04
 
-
+# We install pip and git from https://packages.ubuntu.com/jammy/apt
 RUN apt-get update && \
     apt-get install -y python3-pip git
 
-# Use modern setuptools from pip instead of apt
+# We upgrade pip and install setuptools
 RUN pip3 install pip setuptools --upgrade
 
+# We remove the version of setuptools install via apt, as it is outdated
 RUN apt-get purge -y python3-setuptools
 
 
-# Install mypackage
+# We set the working directory to install docker dependencies
 WORKDIR /tmp/
+
+# We clone the package repo from github and install it and the binder dependencies
 RUN git clone https://github.com/jorgensd/reproducibility && \
-    pip install ./reproducibility[docs]
+    pip install ./reproducibility[binder]
 
+# We remove the contents of the temporary directory to minimize the size of the image
 RUN rm -rf /tmp
 
 # Create user with a home directory
@@ -25,7 +29,7 @@ ARG NB_UID=1000
 ENV USER ${NB_USER}
 ENV HOME /home/${NB_USER}
 
-# Copy home directory for usage in binder
+# Copy home directory for usage with Binder
 WORKDIR ${HOME}
 COPY . ${HOME}
 USER root

pyproject.toml

@@ -1,45 +1,42 @@
-[build-system]
-requires = ["setuptools>=62.1.0", "wheel"]
+[build-system] # Require setuptool version due to https://github.com/pypa/setuptools/issues/2938
+requires = ["setuptools>=61.0.0", "wheel"]
 
-[tool.setuptools]
-package-dir = {"" = "src"}
 
-[tool.setuptools.packages.find]
-where = ["src"]
-
-
-[project]
-name = "mypackage"
-authors = [
+[project] # See https://python-poetry.org/docs/pyproject/ for more keywords
+name = "mypackage" # Name of your package
+authors = [ # List of authors
     {name = "Jørgen S. Dokken", email = "dokken@simula.no"}
     ]
-version = "0.1.0"  
-description = "Minimal package for adding two numbers"
-readme = "README.md"
-requires-python = ">=3.8"
-license = {file = "LICENSE"}
+version = "0.1.0" # Version number
+description = "Minimal package for adding two numbers" # Short description of package
+readme = "README.md" # Is used for the description field in your package, see: https://python-poetry.org/docs/pyproject/#readme
+requires-python = ">=3.8" # Set requirement for minimal python version
+license = {file = "LICENSE"} # Path to license file, see: https://spdx.org/licenses/ for options
 dependencies = [
     'numpy'
 ]
 
 
 [project.optional-dependencies]
 test = [
-   "flake8",
-   "mypy",
-   "pytest",
-   "pytest-cov"
+   "flake8", # Checks code for consistency, see: https://flake8.pycqa.org/en/latest/user/error-codes.html
+   "mypy", # Makes sure that typing of input/output is consistent
+   "pytest", # To run test
+   "pytest-cov" # To create coverage reports
 ]
 
 docs = [
-    "sphinx",
-    "jupyter-book",
-    "jupytext"
+    "jupyter-book", # Required to build documentation
+    "jupytext", # Required to convert .py to .ipynb files
+]
+
+binder = [
+    "jupyterlab" # Required to interface with Binder when having a Dockerfile in root
 ]
 
 [tool.mypy]
-ignore_missing_imports = true
-exclude = [
-    "docs/",
+ignore_missing_imports = true # Does not show errors when importing untyped libraries
+exclude = [ # We only want mypy to consider files that are not generated in installing or building documentation
+    "docs/", 
     "build/"
 ]