Update pyproject.toml (#204)

* Update pyproject.toml

- extend descriptions of build-system table
- add useful links
- edit other comments

* Update pyproject.toml

- be more clear that the values in [build-system] may be generated by the command line interface of the build backend, so the [build-system] table is not required
- reorganize comments to better correspond to their sections

* add changes from #197

add the changes authored by thomasbbrunner in #197

* implement changes from code review

- separate links to guide and specification
- remove text that can already be found by following the provided links
- more accurate comment about the `build-backend` key

* minor: ":"

* better comment about extras

Co-authored-by: chrysle <fritzihab@posteo.de>

* remove # Optional coments, because instead of them we'll mark the REQUIRED fields

---------

Co-authored-by: chrysle <fritzihab@posteo.de>
Co-authored-by: Dustin Ingram <di@users.noreply.github.com>

pyproject.toml

@@ -1,3 +1,19 @@
+# Guide (user-friendly):
+# https://packaging.python.org/en/latest/guides/writing-pyproject-toml/
+
+# Specification (technical, formal):
+# https://packaging.python.org/en/latest/specifications/pyproject-toml/
+
+
+# Choosing a build backend:
+# https://packaging.python.org/en/latest/tutorials/packaging-projects/#choosing-a-build-backend
+[build-system]
+# A list of packages that are needed to build your package:
+requires = ["setuptools"]  # REQUIRED if [build-system] table is used
+# The name of the Python object that frontends will use to perform the build:
+build-backend = "setuptools.build_meta"  # If not defined, then legacy behavior can happen.
+
+
 [project]
 # This is the name of your project. The first time you publish this
 # package, this name will be registered for you. It will determine how
@@ -10,19 +26,19 @@
 # There are some restrictions on what makes a valid project name
 # specification here:
 # https://packaging.python.org/specifications/core-metadata/#name
-name = "sampleproject"  # Required
+name = "sampleproject"  # REQUIRED, is the only field that cannot be marked as dynamic.
 
 # Versions should comply with PEP 440:
 # https://www.python.org/dev/peps/pep-0440/
 #
 # For a discussion on single-sourcing the version, see
 # https://packaging.python.org/guides/single-sourcing-package-version/
-version = "3.0.0"  # Required
+version = "3.0.0"  # REQUIRED, although can be dynamic
 
 # This is a one-line description or tagline of what your project does. This
 # corresponds to the "Summary" metadata field:
 # https://packaging.python.org/specifications/core-metadata/#summary
-description = "A sample Python project"  # Optional
+description = "A sample Python project"
 
 # This is an optional longer description of your project that represents
 # the body of text which users will see when they visit PyPI.
@@ -32,45 +48,45 @@ description = "A sample Python project"  # Optional
 #
 # This field corresponds to the "Description" metadata field:
 # https://packaging.python.org/specifications/core-metadata/#description-optional
-readme = "README.md" # Optional
+readme = "README.md"
 
 # Specify which Python versions you support. In contrast to the
-# 'Programming Language' classifiers, 'pip install' will check this
+# 'Programming Language' classifiers in this file, 'pip install' will check this
 # and refuse to install the project if the version does not match. See
 # https://packaging.python.org/guides/distributing-packages-using-setuptools/#python-requires
-requires-python = ">=3.8"  # Optional
+requires-python = ">=3.8"
 
 # This is either text indicating the license for the distribution, or a file
 # that contains the license.
 # https://packaging.python.org/en/latest/specifications/core-metadata/#license
-license = {file = "LICENSE.txt"}  # Optional
+license = {file = "LICENSE.txt"}
 
 # This field adds keywords for your project which will appear on the
 # project page. What does your project relate to?
 #
 # Note that this is a list of additional keywords, separated
 # by commas, to be used to assist searching for the distribution in a
 # larger catalog.
-keywords = ["sample", "setuptools", "development"]  # Optional
+keywords = ["sample", "setuptools", "development"]
 
 # This should be your name or the name of the organization who originally
 # authored the project, and a valid email address corresponding to the name
 # listed.
 authors = [
-  {name = "A. Random Developer", email = "author@example.com" } # Optional
+  {name = "A. Random Developer", email = "author@example.com" }
 ]
 
 # This should be your name or the names of the organization who currently
 # maintains the project, and a valid email address corresponding to the name
 # listed.
 maintainers = [
-  {name = "A. Great Maintainer", email = "maintainer@example.com" } # Optional
+  {name = "A. Great Maintainer", email = "maintainer@example.com" }
 ]
 
 # Classifiers help users find your project by categorizing it.
 #
 # For a list of valid classifiers, see https://pypi.org/classifiers/
-classifiers = [  # Optional
+classifiers = [
   # How mature is this project? Common values are
   #   3 - Alpha
   #   4 - Beta
@@ -86,7 +102,7 @@ classifiers = [  # Optional
 
   # Specify the Python versions you support here. In particular, ensure
   # that you indicate you support Python 3. These classifiers are *not*
-  # checked by "pip install". See instead "requires-python".
+  # checked by "pip install". See instead "requires-python" key in this file.
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3.8",
   "Programming Language :: Python :: 3.9",
@@ -102,7 +118,7 @@ classifiers = [  # Optional
 #
 # For an analysis of this field vs pip's requirements files see:
 # https://packaging.python.org/discussions/install-requires-vs-requirements/
-dependencies = [ # Optional
+dependencies = [
   "peppercorn"
 ]
 
@@ -112,9 +128,10 @@ dependencies = [ # Optional
 #
 #   $ pip install sampleproject[dev]
 #
-# Similar to `dependencies` above, these must be valid existing
-# projects.
-[project.optional-dependencies] # Optional
+# Optional dependencies the project provides. These are commonly 
+# referred to as "extras". For a more extensive definition see:
+# https://packaging.python.org/en/latest/specifications/dependency-specifiers/#extras
+[project.optional-dependencies]
 dev = ["check-manifest"]
 test = ["coverage"]
 
@@ -128,7 +145,7 @@ test = ["coverage"]
 # issues, where the source is hosted, where to say thanks to the package
 # maintainers, and where to support the project financially. The key is
 # what's used to render the link text on PyPI.
-[project.urls]  # Optional
+[project.urls]
 "Homepage" = "https://github.com/pypa/sampleproject"
 "Bug Reports" = "https://github.com/pypa/sampleproject/issues"
 "Funding" = "https://donate.pypi.org"
@@ -137,18 +154,13 @@ test = ["coverage"]
 
 # The following would provide a command line executable called `sample`
 # which executes the function `main` from this package when invoked.
-[project.scripts]  # Optional
+[project.scripts]
 sample = "sample:main"
 
+
 # This is configuration specific to the `setuptools` build backend.
 # If you are using a different build backend, you will need to change this.
 [tool.setuptools]
 # If there are data files included in your packages that need to be
 # installed, specify them here.
 package-data = {"sample" = ["*.dat"]}
-
-[build-system]
-# These are the assumed default build requirements from pip:
-# https://pip.pypa.io/en/stable/reference/pip/#pep-517-and-518-support
-requires = ["setuptools>=43.0.0", "wheel"]
-build-backend = "setuptools.build_meta"