Describe building of semver

tomschr · tomschr · commit 68e3368d436a · 2022-10-04T21:59:46.000+02:00
diff --git a/BUILDING.rst b/BUILDING.rst
@@ -0,0 +1,59 @@
+.. _build-semver:
+
+Building semver
+===============
+
+.. _PEP 517: https://www.python.org/dev/peps/pep-0517/
+.. _PEP 621: https://www.python.org/dev/peps/pep-0621/
+.. _A Practical Guide to Setuptools and Pyproject.toml: https://godatadriven.com/blog/a-practical-guide-to-setuptools-and-pyproject-toml/
+.. _Declarative config: https://setuptools.rtfd.io/en/latest/userguide/declarative_config.html
+
+
+This project changed slightly its way how it is built. The reason for this
+was to still support the "traditional" way with :command:`setup.py`,
+but at the same time try out the newer way with :file:`pyproject.toml`.
+Over time, once Python 3.6 gets deprecated, we will support only the newer way.
+
+
+Background information
+----------------------
+
+Skip this section and head over to :ref:`build-pyproject-build` if you just
+want to know how to build semver.
+This section gives some background information how this project is set up.
+
+The traditional way with :command:`setup.py` in this project uses a
+`Declarative config`_. With this approach, the :command:`setup.py` is
+stripped down to its bare minimum and all the metadata is stored in
+:file:`setup.cfg`.
+
+The new :file:`pyproject.toml` contains only information about the build backend, currently setuptools.build_meta. The idea is taken from
+`A Practical Guide to Setuptools and Pyproject.toml`_.
+Setuptools-specific configuration keys as defined in `PEP 621`_ are currently
+not used.
+
+
+.. _build-pyproject-build:
+
+Building with pyproject-build
+-----------------------------
+
+To build semver you need:
+
+* The :mod:`build` module which implements the `PEP 517`_ build
+  frontend.
+  Install it with::
+
+        pip install build
+
+  Some Linux distributions has already packaged it. If you prefer
+  to use the module with your package manager, search for
+  :file:`python-build` or :file:`python3-build` and install it.
+
+* The command :command:`pyproject-build` from the :mod:`build` module.
+
+To build semver, run::
+
+    pyproject-build
+
+After the command is finished, you can find two files in the :file:`dist` folder: a ``.tar.gz`` and a ``.whl`` file.
diff --git a/changelog.d/364.feature.rst b/changelog.d/364.feature.rst
@@ -0,0 +1,3 @@
+Enhance :file:`pyproject.toml` to make it possible to use the
+:command:`pyproject-build` command from the build module.
+For more information, see :ref:`build-semver`.
diff --git a/docs/building.rst b/docs/building.rst
@@ -1,34 +1 @@
-Building semver
-===============
-
-.. _PEP 517: https://www.python.org/dev/peps/pep-0517/
-
-This project changed its way how it is built. The reason for this
-was to still support the "traditional" way, but at the same time
-try out the newer way with ``pyproject.toml``. Over time, once
-Python 3.6 gets deprecated, we will support only the newer way.
-
-We distinguish between different Python versions:
-
-* For Python 3.6: Uses the usual :command:`setup.py build`.
-
-* From Python 3.7 and above: Uses the more modern approach
-  with the `PEP 517`_ build frontend and its command
-  :command:`pyproject-build`, implemented in https://github.com/pypa/build.
-
-Both ways are integrated into the :command:`build.sh` script. The
-script will detect your used Python version and uses either the old
-or new way.
-
-For you as developer or packager you can:
-
-* use the :command:`build.sh` script and don't care about
-  the background, or
-
-* ignore the :command:`build.sh` script and use the usual :command:`setup.py`
-  command or :command:`pyproject-build`, depending on your Python version.
-
-.. "setuptools>=62.0",
-   "setuptools-scm",
-   "wheel",
-   "build",
+.. include:: ../BUILDING.rst

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	+Enhance :file:`pyproject.toml` to make it possible to use the
	`2`	+:command:`pyproject-build` command from the build module.
	`3`	+For more information, see :ref:`build-semver`.