Added documentation for build_meta

changelog.d/1698.doc.rst

@@ -0,0 +1 @@
+Added documentation for ``build_meta`` (a bare minimum, not completed).

docs/build_meta.txt

@@ -0,0 +1,95 @@
+=======================================
+Build System Support
+=======================================
+
+What is it?
+-------------
+
+Python packaging has come `a long way <https://www.bernat.tech/pep-517-518/>`_.
+
+The traditional ``setuptools`` way of packgaging Python modules
+uses a ``setup()`` function within the ``setup.py`` script. Commands such as
+``python setup.py bdist`` or ``python setup.py bdist_wheel`` generate a 
+distribution bundle and ``python setup.py install`` installs the distribution. 
+This interface makes it difficult to choose other packaging tools without an 
+overhaul. Because ``setup.py`` scripts allowed for arbitrary execution, it
+proved difficult to provide a reliable user experience across environments
+and history.
+
+`PEP 517 <https://www.python.org/dev/peps/pep-0517/>`_ therefore came to
+rescue and specified a new standard to 
+package and distribute Python modules. Under PEP 517:
+
+    a ``pyproject.toml`` file is used to specify what program to use
+    for generating distribution. 
+
+    Then, two functions provided by the program, ``build_wheel(directory: str)`` 
+    and ``build_sdist(directory: str)`` create the distribution bundle at the 
+    specified ``directory``. The program is free to use its own configuration 
+    script or extend the ``.toml`` file. 
+
+    Lastly, ``pip install *.whl`` or ``pip install *.tar.gz`` does the actual
+    installation. If ``*.whl`` is available, ``pip`` will go ahead and copy
+    the files into ``site-packages`` directory. If not, ``pip`` will look at
+    ``pyproject.toml`` and decide what program to use to 'build from source' 
+    (the default is ``setuptools``)
+
+With this standard, switching between packaging tools becomes a lot easier and
+in the case of ``setuptools``, ``setup.py`` becomes optional.
+
+``build_meta`` is ``setuptools``'s implementation of PEP 517. It provides the 
+two functions, ``build_wheel`` and ``build_sdist`` amongst others, and uses 
+a ``setup.cfg`` to specify the information about the package. 
+
+How to use it?
+--------------
+
+Starting with a package that you want to distribute. You will need your source
+scripts, a ``pyproject.toml`` file and a ``setup.cfg`` file::
+
+    ~/meowpkg/
+        pyproject.toml
+        setup.cfg
+        meowpkg/__init__.py
+
+The pyproject.toml file is required to specify the build system (i.e. what is 
+being used to package your scripts and install from source). To use it with 
+setuptools, the content would be::
+
+    [build-system]
+    requires = ["setuptools", "wheel"]
+    build-backend = "setuptools.build_meta" 
+
+Use ``setup.cfg`` to specify your package information, specified 
+`here <https://setuptools.readthedocs.io/en/latest/setuptools.html#configuring
+-setup-using-setup-cfg-files>`_ ::
+
+    [metadata]
+    name = meowpkg
+    version = 0.0.1
+    description = a package that meows
+
+    [options]
+    packages = find:
+
+Now generate the distribution. Although the PyPA is still working to
+`provide a recommended tool <https://github.com/pypa/packaging-problems/issues/219>`_
+to build packages, the `pep517 package <https://pypi.org/project/pep517`_
+provides this functionality. To build the package::
+
+    $ pip install -q pep517
+    $ mkdir dist
+    $ python -m pep517.build .
+
+And now it's done! The ``.whl`` file  and ``.tar.gz`` can then be distributed 
+and installed::
+
+    dist/
+        meowpkg-0.0.1.whl
+        meowpkg-0.0.1.tar.gz
+
+    $ pip install dist/meowpkg-0.0.1.whl
+
+or::
+
+    $ pip install dist/meowpkg-0.0.1.tar.gz