Update documentation

CHANGELOG.md

@@ -1,6 +1,7 @@
 v2.3.0 (in development)
 -----------------------
 - Always read `.hg_archival.txt` files using UTF-8 encoding
+- Added support for using versioningit with [Hatch](https://hatch.pypa.io)
 
 v2.2.1 (2023-09-22)
 -------------------

README.rst

@@ -41,6 +41,10 @@ calculation.
 
 - Supports Git, modern Git archives, and Mercurial
 
+- *(New in version 2.3.0)* `Works with Hatch`__
+
+  __ https://versioningit.readthedocs.io/en/stable/hatch.html
+
 - Formatting of the final version uses format template strings, with fields for
   basic VCS information and separate template strings for distanced vs. dirty
   vs. distanced-and-dirty repository states

docs/api.rst

@@ -3,8 +3,8 @@
 Library API
 ===========
 
-High-Level Functions
---------------------
+High-Level Functions and Classes
+--------------------------------
 
 .. autofunction:: get_version
 .. autofunction:: get_next_version

docs/changelog.rst

@@ -6,6 +6,7 @@ Changelog
 v2.3.0 (in development)
 -----------------------
 - Always read :file:`.hg_archival.txt` files using UTF-8 encoding
+- Added support for using versioningit with `Hatch <https://hatch.pypa.io>`_
 
 
 v2.2.1 (2023-09-22)

docs/configuration.rst

@@ -498,6 +498,18 @@ which takes the following parameters:
         This file should not be committed to version control, but it should be
         included in your project's built sdists and wheels.
 
+    .. note::
+
+        If you're using Hatch and you followed the advice above by adding the
+        file to your :file:`.gitignore` or :file:`.hgignore`, then you will
+        need to tell Hatch to include the file in sdists & wheels like so:
+
+        .. code:: toml
+
+            [tool.hatch.build]
+            # Replace the path below with the value you gave to the "file" key:
+            artifacts = ["src/mypackage/_version.py"]
+
 ``encoding`` : string
     *(optional)* The encoding with which to write the file.  Defaults to UTF-8.
 
@@ -675,10 +687,10 @@ time by running the ``versioningit`` command (See ":ref:`command`").
 Log Level Environment Variable
 ------------------------------
 
-When ``versioningit`` is invoked via the setuptools plugin interface, it logs
-various information to stderr.  By default, only messages at ``WARNING`` level
-or higher are displayed, but this can be changed by setting the
-:envvar:`VERSIONINGIT_LOG_LEVEL` environment variable to the name of a Python
-`logging level`_ (case insensitive) or the equivalent integer value.
+When ``versioningit`` is invoked via the setuptools or Hatch plugin interface,
+it logs various information to stderr.  By default, only messages at
+``WARNING`` level or higher are displayed, but this can be changed by setting
+the :envvar:`VERSIONINGIT_LOG_LEVEL` environment variable to the name of a
+Python `logging level`_ (case insensitive) or the equivalent integer value.
 
 .. _logging level: https://docs.python.org/3/library/logging.html#logging-levels

docs/hatch.rst

@@ -0,0 +1,98 @@
+Hatch Integration
+=================
+
+.. versionadded:: 2.3.0
+
+If you're not a setuptools user, ``versioningit`` can also be used as a version
+source plugin for the Hatch_ build backend.  You use it in pretty much the same
+way as for setuptools:
+
+.. _Hatch: https://hatch.pypa.io
+
+- Include ``versioningit`` in your build requirements like so:
+
+    .. code:: toml
+
+        [build-system]
+        requires = ["hatchling", "versioningit"]
+        build-backend = "hatchling.build"
+
+- Tell Hatch that you're using a dynamic version source by including
+  ``"version"`` in the ``project.dynamic`` key:
+
+    .. code:: toml
+
+        [project]
+        name = "your-project-name"
+        dynamic = ["version"]
+        # The rest of your project metadata follows after.
+
+        # Do not set the `version` key in [project].  If it's currently set,
+        # remove it.
+
+- Tell Hatch to use ``versioningit`` as the version source:
+
+    .. code:: toml
+
+        [tool.hatch.version]
+        source = "versioningit"
+
+- Configure ``versioningit`` as normal.  However, with Hatch, you have two
+  possible locations to put ``versioningit``'s configuration in: either a
+  ``[tool.versioningit]`` table as used with setuptools or under the
+  ``[tool.hatch.version]`` table.  Moreover, unlike when using setuptools, you
+  don't even need the ``[tool.versioningit]`` table if it's just going to be
+  empty.
+
+  For example, the following configurations are equivalent:
+
+    - Using ``[tool.versioningit]``:
+
+        .. code:: toml
+
+            [tool.hatch.version]
+            source = "versioningit"
+
+            [tool.versioningit]
+            default-version = "0.0.0+unknown"
+
+            [tool.versioningit.format]
+            distance = "{next_version}.dev{distance}+{vcs}{rev}"
+            dirty = "{version}+dirty"
+            distance-dirty = "{next_version}.dev{distance}+{vcs}{rev}.dirty"
+
+    - Using ``[tool.hatch.version]``:
+
+        .. code:: toml
+
+            [tool.hatch.version]
+            source = "versioningit"
+            default-version = "0.0.0+unknown"
+
+            [tool.hatch.version.format]
+            distance = "{next_version}.dev{distance}+{vcs}{rev}"
+            dirty = "{version}+dirty"
+            distance-dirty = "{next_version}.dev{distance}+{vcs}{rev}.dirty"
+
+    If you configure ``versioningit`` via ``[tool.hatch.version]`` and also
+    define a ``[tool.versioningit]`` table (even if it's empty), a warning will
+    be emitted, and only the ``[tool.hatch.version]`` configuration will be
+    used.
+
+- If you use the ``write`` step to create a file containing your project
+  version, and this file is listed in your :file:`.gitignore` or
+  :file:`.hgignore`, you will need to tell Hatch to include the file in sdists
+  & wheels like so:
+
+    .. code:: toml
+
+        [tool.hatch.build]
+        # Replace the path below with the path to the file created by the
+        # `write` step:
+        artifacts = ["src/mypackage/_version.py"]
+
+.. note::
+
+    If you use ``versioningit`` with Hatch, you will not be able to set your
+    project's version by running ``hatch version x.y.z``.  Just create a tag
+    instead!

docs/how.rst

@@ -4,7 +4,7 @@ How it Works
 ``versioningit`` divides its operation into seven :dfn:`steps`: ``vcs``,
 ``tag2version``, ``next-version``, ``format``, ``template-fields``, ``write``,
 and ``onbuild``.  The first four steps make up the actual version calculation,
-while the rest normally only happen while building with setuptools.
+while the rest normally only happen while building with setuptools or Hatch.
 
 Version Calculation
 -------------------
@@ -34,25 +34,25 @@ The version for a given project is determined as follows:
   ``onbuild`` steps
 
 
-Setuptools Integration
-----------------------
+Build Integration
+-----------------
 
 Setting the Version
 ^^^^^^^^^^^^^^^^^^^
 
-``versioningit`` registers a ``setuptools.finalize_distribution_options`` entry
-point that causes it to be run whenever setuptools computes the metadata for a
-project in an environment in which ``versioningit`` is installed.  If the
-project in question has a :file:`pyproject.toml` file with a
-``[tool.versioningit]`` table, then ``versioningit`` performs the version
-calculations described above and sets the project's version to the final value.
-(If a version cannot be determined because the project is not in a repository
-or repository archive, then ``versioningit`` will assume the project is an
+``versioningit`` registers plugins with both setuptools and Hatch that cause it
+to be run whenever one of those backends computes the metadata for a project in
+an environment in which ``versioningit`` is installed.  If the project in
+question has a :file:`pyproject.toml` file with a ``[tool.versioningit]`` table
+(or, for Hatch only, a ``[tool.hatch.version]`` table containing more than just
+a ``source`` key), then ``versioningit`` performs the version calculations
+described above and sets the project's version to the final value.  (If a
+version cannot be determined because the project is not in a repository or
+repository archive, then ``versioningit`` will assume the project is an
 unpacked sdist and will look for a :file:`PKG-INFO` file to fetch the version
-from instead.)  If the :file:`pyproject.toml` contains a
-``[tool.versioningit.write]`` table, then the ``write`` step will also be run
-at this time; the default ``write`` method creates a file at a specified path
-containing the project's version.
+from instead.)  If the configuration table contains a ``write`` subtable, then
+the ``write`` step will also be run at this time; the default ``write`` method
+creates a file at a specified path containing the project's version.
 
 ``onbuild`` Step
 ^^^^^^^^^^^^^^^^

docs/index.rst

@@ -16,6 +16,7 @@ versioningit — Versioning It with your Version In Git
     how
     configuration
     runtime-version
+    hatch
     command
     api
     writing-methods
@@ -34,6 +35,8 @@ calculation.
 
 - Supports Git, modern Git archives, and Mercurial
 
+- *(New in version 2.3.0)* :doc:`Works with Hatch <hatch>`
+
 - Formatting of the final version uses format template strings, with fields for
   basic VCS information and separate template strings for distanced vs. dirty
   vs. distanced-and-dirty repository states

src/versioningit/__init__.py

@@ -12,6 +12,8 @@
 
 - Supports Git, modern Git archives, and Mercurial
 
+- *(New in version 2.3.0)* Works with Hatch
+
 - Formatting of the final version uses format template strings, with fields for
   basic VCS information and separate template strings for distanced vs. dirty
   vs. distanced-and-dirty repository states