Update packaging guide to refer to 'flit'

Author: greschd

doc/source/library_description/packaging.rst

@@ -11,13 +11,10 @@ Namespace Packaging
 -------------------
 A PyAnsys library uses `namespace packaging`_.
 Namespace packages allow a user to easily split subpackages from a package into
-a single, independent distribution.
+single, independent distributions.
 
-Three different approaches are currently available for creating a namespace package:
-
-* `native namespace packages`_
-* pkgutil-style namespace packages
-* pkg_resources-style namespace packages
+There are different approaches available for creating a namespace package. For the
+``ansys`` namespace, we use the `PEP 420`_ `native namespace packages`_ approach.
 
 Required Files
 --------------
@@ -27,48 +24,71 @@ Required Files
 
 * LICENSE file: Specifies copyrights and required authorization.
 
-* setup.py file: Provides package information.
-  The presence of this file indicate that the package was likely created using ``disutils``,
-  which is the Python standard for building and distributing a Python package.
+* pyproject.toml file: Provides package information.
+  This file provides the package metadata, and defines how it is built.
+  There are different build backends available, such as `setuptools`_,
+  `poetry`_ and `flit`_.
 
 
-Setup File
-----------
-The `setup.py`_ file is the build script for ``setuptools``. It exposes dynamic metadata and contains
-package information, such as a description, author, and version.
-In this file, the ``setuptools`` module is used to configure the metadata (as opposed to ``distutils``).
+Project Configuration File
+--------------------------
 
-.. code:: python
+The ``pyproject.toml`` file is the standardized build configuration file for Python
+projects. It needs to at least contain a ``[build-system]`` section, which determines
+how the project is built. Some commonly used packaging tools are `setuptools`_,
+`poetry`_, or `flit`_.
+
+When writing a *library*, `flit`_ is a good default choice. For *applications*,
+`poetry`_ is a good default as it provides features to pin dependency versions.
+We use `flit`_ in the template repository and the description below.
+
+To use `flit`_ as a packaging tool, the ``pyproject.toml`` should contain
+
+.. code:: toml
 
-  import setuptools
-  setuptools.setup(...)
+  [build-system]
+  requires = ["flit_core >=3.2,<4"]
+  build-backend = "flit_core.buildapi"
 
-This file gathers all namespace packages and files that must be included in the distributed
-package.
+The ``[project]`` section contains metadata, and defines the project's dependencies. Refer to the
+`flit metadata documentation`_ for details.
+
+Flit can automatically determine the project's version from the source code.
+In the ``[project]`` section, add
+
+.. code:: toml
+
+  dynamic = ["version"]
+
+The version is parsed from the ``ansys/package/library/__init__.py`` file, which must
+contain a statement
 
 .. code:: python
 
-  packages = []
-  for package in setuptools.find_namespace_packages(include='ansys*'):
-      if package.startswith('ansys.tools.example_coverage'):
-          packages.append(package)
+  __version__ = "0.1.0"
+
+Where supported, we aim to put all tooling-related configuration into ``pyproject.toml``.
+For example, it can also be used to configure the code formatter `black`_ or the static
+type checker `mypy`_.
 
+.. note::
 
-It also extracts the version number from the ``_version.py`` file located in the 
-``ansys/<product>/library`` directory of the source code.
+  When using `setuptools`_ as a build backend, providing the metadata in ``pyproject.toml`` is not yet fully supported.
+  Instead, it also requires a ``setup.cfg`` and / or ``setup.py`` file.
 
 
 Generate the Package and Upload It on PyPI
 ------------------------------------------
 
-The first time that you want to upload a package on PyPI under the `ansys <https://pypi.org/user/ansys/>`_ 
+The first time that you want to upload a package on PyPI under the `ansys <https://pypi.org/user/ansys/>`_
 account, you must perform the following process manually.
 
 Create the python package.
 
 .. code::
 
-  python setup.py sdist
+  pip install build
+  python -m build
 
 Verify the distribution's long description rendering with ``twine``.
 
@@ -77,7 +97,7 @@ Verify the distribution's long description rendering with ``twine``.
   pip install twine
   twine check dist/*
 
-Upload the package to PyPI using ``twine`` and the upload token generated for the ``ansys`` PyPI account. 
+Upload the package to PyPI using ``twine`` and the upload token generated for the ``ansys`` PyPI account.
 Contact [email protected] for the token.
 
 .. code::
@@ -127,7 +147,7 @@ Install a package with:
 
 .. code::
 
-  pip install ansys.<product>.<library>
+  pip install ansys-<product>-<library>
 
 To create a package complying with the above standards, here is the minimal content of your PyAnsys library:
 
@@ -136,12 +156,19 @@ To create a package complying with the above standards, here is the minimal cont
    ansys/<product>/<library>/__init__.py
    LICENSE
    README.rst
-   setup.py
+   pyproject.toml
    tests/
 
 
 .. _namespace packaging: https://packaging.python.org/guides/packaging-namespace-packages/
 .. _native namespace packages: https://packaging.python.org/guides/packaging-namespace-packages/#native-namespace-packages
+.. _PEP 420: https://www.python.org/dev/peps/pep-0420/
+.. _setuptools: https://setuptools.pypa.io
+.. _poetry: https://python-poetry.org/docs/
+.. _flit: https://flit.readthedocs.io
+.. _flit metadata documentation: https://flit.readthedocs.io/en/latest/pyproject_toml.html#new-style-metadata
+.. _black: https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#configuration-via-a-file
+.. _mypy: https://mypy.readthedocs.io/en/stable/config_file.html#the-mypy-configuration-file
 .. _trunk-based development: https://trunkbaseddevelopment.com/
 .. _secret: https://docs.github.com/en/actions/reference/encrypted-secrets
 .. _setup.py: https://packaging.python.org/tutorials/packaging-projects/#configuring-metadata