Start documenting PEP 621 support

doc/pyproject_toml.rst

@@ -20,13 +20,214 @@ defined by PEP 517. For any project using Flit, it will look like this:
 .. code-block:: toml
 
     [build-system]
-    requires = ["flit_core >=2,<4"]
+    requires = ["flit_core >=3.2,<4"]
     build-backend = "flit_core.buildapi"
 
-Metadata section
-----------------
+.. _pyproject_toml_project:
+
+New style metadata
+------------------
+
+.. versionadded:: 3.2
+
+The new standard way to specify project metadata is in a ``[project]`` table,
+as defined by :pep:`621`. Flit works for now with either this or the older
+``[tool.flit.metadata]`` table (:ref:`described below <pyproject_old_metadata>`),
+but it won't allow you to mix them.
+
+A simple ``[project]`` table might look like this:
+
+.. code-block:: toml
+
+    [project]
+    name = "astcheck"
+    authors = [
+        {name = "Thomas Kluyver", email = "[email protected]"},
+    ]
+    readme = "README.rst"
+    classifiers = [
+        "License :: OSI Approved :: MIT License",
+    ]
+    requires-python = ">=3.5"
+    dynamic = ['version', 'description']
+
+The allowed fields are:
+
+name
+  The name your package will have on PyPI. This field is required. For Flit,
+  this also points to your package as an import name by default (see ... if
+  that needs to be different).
+version
+  Version number as a string. If you want Flit to get this from a
+  ``__version__`` attribute, leave it out of the TOML config and include
+  "version" in the ``dynamic`` field.
+description
+  A one-line description of your project. If you want Flit to get this from
+  the module docstring, leave it out of the TOML config and include
+  "description" in the ``dynamic`` field.
+readme
+  A path (relative to the .toml file) to a file containing a longer description
+  of your package to show on PyPI. This should be written in `reStructuredText
+  <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_, Markdown or
+  plain text, and the filename should have the appropriate extension
+  (``.rst``, ``.md`` or ``.txt``). Alternatively, ``readme`` can be a table with
+  either a ``file`` key (a relative path) or a ``text`` key (literal text), and
+  an optional ``content-type`` key (e.g. ``text/x-rst``).
+requires-python
+  A version specifier for the versions of Python this requires, e.g. ``~=3.3`` or
+  ``>=3.3,<4``, which are equivalents.
+license
+  A table with either a ``file`` key (a relative path to a license file) or a
+  ``text`` key (the license text).
+authors
+  A list of tables with ``name`` and ``email`` keys (both optional) describing
+  the authors of the project.
+maintainers
+  Same format as authors.
+keywords
+  A list of words to help with searching for your package.
+classifiers
+  A list of `Trove classifiers <https://pypi.python.org/pypi?%3Aaction=list_classifiers>`_.
+  Add ``Private :: Do Not Upload`` into the list to prevent a private package
+  from being uploaded to PyPI by accident.
+dependencies & optional-dependencies
+  See :ref:`pyproject_project_dependencies`.
+urls
+  See :ref:`pyproject_project_urls`.
+scripts & gui-scripts
+  See :ref:`pyproject_project_scripts`.
+entry-points
+  See :ref:`pyproject_project_entrypoints`.
+dynamic
+  A list of field names which aren't specified here, for which Flit should
+  find a value at build time. Only "version" and "description" are accepted.
+
+.. _pyproject_project_dependencies:
+
+Dependencies
+~~~~~~~~~~~~
+
+The ``dependencies`` field is a list of other packages from PyPI that this
+package needs. Each package may be followed by a version specifier like
+``>=4.1``, and/or an `environment marker
+<https://www.python.org/dev/peps/pep-0508/#environment-markers>`_
+after a semicolon. For example:
+
+  .. code-block:: toml
+
+      dependencies = [
+          "requests >=2.6",
+          "configparser; python_version == '2.7'",
+      ]
+
+The ``[project.optional-dependencies]`` table contains lists of packages needed
+for every optional feature. The requirements are specified in the same format as
+for ``dependencies``. For example:
+
+  .. code-block:: toml
+
+      [project.optional-dependencies]
+      test = [
+          "pytest >=2.7.3",
+          "pytest-cov",
+      ]
+      doc = ["sphinx"]
+
+You can call these optional features anything you want, although ``test`` and
+``doc`` are common ones. You specify them for installation in square brackets
+after the package name or directory, e.g. ``pip install '.[test]'``.
+
+.. _pyproject_project_urls:
+
+URLs table
+~~~~~~~~~~
+
+Your project's page on `pypi.org <https://pypi.org/>`_ can show a number of
+links. You can point people to documentation or a bug tracker, for example.
+
+This section is called ``[project.urls]`` in the file. You can use
+any names inside it. Here it is for flit:
+
+.. code-block:: toml
+
+  [project.urls]
+  Documentation = "https://flit.readthedocs.io/en/latest/"
+  Source = "https://github.com/takluyver/flit"
+
+.. _pyproject_project_scripts:
+
+Scripts section
+~~~~~~~~~~~~~~~
+
+This section is called ``[project.scripts]`` in the file.
+Each key and value describes a shell command to be installed along with
+your package. These work like setuptools 'entry points'. Here's the section
+for flit:
+
+.. code-block:: toml
+
+    [project.scripts]
+    flit = "flit:main"
+
+
+This will create a ``flit`` command, which will call the function ``main()``
+imported from :mod:`flit`.
+
+A similar table called ``[project.gui-scripts]`` defines commands which launch
+a GUI. This only makes a difference on Windows, where GUI scripts are run
+without a console.
+
+.. _pyproject_project_entrypoints:
+
+Entry points sections
+~~~~~~~~~~~~~~~~~~~~~
+
+You can declare `entry points <http://entrypoints.readthedocs.io/en/latest/>`_
+using sections named :samp:`[project.entry-points.{groupname}]`. E.g. to
+provide a pygments lexer from your package:
+
+.. code-block:: toml
+
+    [project.entry-points."pygments.lexers"]
+    dogelang = "dogelang.lexer:DogeLexer"
+
+In each ``package:name`` value, the part before the colon should be an
+importable module name, and the latter part should be the name of an object
+accessible within that module. The details of what object to expose depend on
+the application you're extending.
+
+If the group name contains a dot, it must be quoted (``"pygments.lexers"``
+above). Script entry points are defined in :ref:`scripts tables
+<pyproject_project_scripts>`, so you can't use the group names
+``console_scripts`` or ``gui_scripts`` here.
+
+Module section
+~~~~~~~~~~~~~~
+
+If your package will have different names for installation and import,
+you should specify the install (PyPI) name in the ``[project]`` table
+(:ref:`see above <pyproject_toml_project>`), and the import name in a
+``[tool.flit.module]`` table:
+
+.. code-block:: toml
+
+    [project]
+    name = "pynsist"
+    # ...
+
+    [tool.flit.module]
+    name = "nsist"
+
+.. _pyproject_old_metadata:
+
+Old style metadata
+------------------
+
+Flit's older way to specify metadata is in a ``[tool.flit.metadata]`` table,
+along with ``[tool.flit.scripts]`` and ``[tool.flit.entrypoints]``, described
+below. This is still recognised for now, but you can't mix it with
+:ref:`pyproject_toml_project`.
 
-This section is called ``[tool.flit.metadata]`` in the file.
 There are three required fields:
 
 module
@@ -140,7 +341,7 @@ URLs subsection
 ~~~~~~~~~~~~~~~
 
 Your project's page on `pypi.org <https://pypi.org/>`_ can show a number of
-links, in addition to the required ``home-page`` URL described above. You can
+links, in addition to the ``home-page`` URL described above. You can
 point people to documentation or a bug tracker, for example.
 
 This section is called ``[tool.flit.metadata.urls]`` in the file. You can use
@@ -156,38 +357,18 @@ any names inside it. Here it is for flit:
 .. _pyproject_toml_scripts:
 
 Scripts section
----------------
-
-This section is called ``[tool.flit.scripts]`` in the file.
-Each key and value describes a shell command to be installed along with
-your package. These work like setuptools 'entry points'. Here's the section
-for flit:
-
-.. code-block:: toml
-
-    [tool.flit.scripts]
-    flit = "flit:main"
+~~~~~~~~~~~~~~~
 
-
-This will create a ``flit`` command, which will call the function ``main()``
-imported from :mod:`flit`.
+A ``[tool.flit.scripts]`` table can be used along with ``[tool.flit.metadata]``.
+It is in the same format as the newer ``[project.scripts]`` table
+:ref:`described above <pyproject_project_scripts>`.
 
 Entry points sections
----------------------
-
-You can declare `entry points <http://entrypoints.readthedocs.io/en/latest/>`_
-using sections named :samp:`[tool.flit.entrypoints.{groupname}]`. E.g. to
-provide a pygments lexer from your package:
-
-.. code-block:: toml
+~~~~~~~~~~~~~~~~~~~~~
 
-    [tool.flit.entrypoints."pygments.lexers"]
-    dogelang = "dogelang.lexer:DogeLexer"
-
-In each ``package:name`` value, the part before the colon should be an
-importable module name, and the latter part should be the name of an object
-accessible within that module. The details of what object to expose depend on
-the application you're extending.
+``[tool.flit.entrypoints]`` tables can be used along with ``[tool.flit.metadata]``.
+They are in the same format as the newer ``[project.entry-points]`` tables
+:ref:`described above <pyproject_project_entrypoints>`.
 
 .. _pyproject_toml_sdist: