From a4fab47b8632a6bfae83cb5bf38728f436509afb Mon Sep 17 00:00:00 2001 From: "John T. Wodder II" Date: Sun, 19 Nov 2023 08:02:51 -0500 Subject: [PATCH] Some docs improvements --- docs/configuration.rst | 89 +++++++++++++++++++++++++--------------- docs/runtime-version.rst | 11 +++-- 2 files changed, 62 insertions(+), 38 deletions(-) diff --git a/docs/configuration.rst b/docs/configuration.rst index 09d241b..a84b6da 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -184,19 +184,15 @@ method provides the ``format`` step with only a subset of the fields that the .. topic:: A note on Git version requirements - The ``%(describe)s`` placeholder was only added to Git in version 2.32.0, - and so a Git repository archive must be created using at least that - version in order to be installable with this method. Fortunately, GitHub - repository ZIP downloads support ``%(describe)``, and so + and the "tags" option was added in Git 2.35.0. A Git repository archive + must be created with a Git of the appropriate minimum version in order to + be installable with this method. + + Fortunately, GitHub repository ZIP downloads currently support both + ``%(describe)`` and ``%(describe:tags)``, and so :command:`pip`-installing a "git-archive"-using project from a URL of the form ``https://github.com/$OWNER/$REPO/archive/$BRANCH.zip`` will work. - - The ``%(describe)s`` placeholder only gained support for the "tags" - option in Git 2.35.0, and so, if this option is included in the - ``describe-subst`` parameter, that Git version or higher will be required - when creating a repository archive in order for the result to be - installable. Unfortunately, as of 2022-02-05, GitHub repository Zips do - not support this option. - - When installing from a Git repository rather than an archive, the "git-archive" method parses the ``describe-subst`` parameter into the equivalent ``git describe`` options, so a bleeding-edge Git is not @@ -545,8 +541,6 @@ which takes the following parameters: The ``[tool.versioningit.onbuild]`` Subtable -------------------------------------------- -.. versionadded:: 1.1.0 - .. attention:: Currently, the ``onbuild`` step is not supported when using @@ -554,40 +548,71 @@ The ``[tool.versioningit.onbuild]`` Subtable __ https://github.com/jwodder/versioningit/issues/54 +.. versionadded:: 1.1.0 + +.. versionadded:: 2.2.0 + + ``sdist`` and ``build_py`` classes added for use in :file:`setup.cfg` and + :file:`pyproject.toml` + The ``onbuild`` subtable configures an optional feature, inserting the project version and/or other fields into built project trees when building an sdist or wheel. Specifically, this feature allows you to create sdists & wheels in which some file has been modified to contain the line ``__version__ = ""`` or similar while leaving your repository alone. -In order to use this feature, in addition to filling out the subtable, your -project must include a :file:`setup.py` file that passes -`versioningit.get_cmdclasses()` as the ``cmdclass`` argument to `setup()`, -e.g.: +Enabling ``onbuild`` +~~~~~~~~~~~~~~~~~~~~ -.. code:: python +In order to use this feature, in addition to filling out the subtable, you must +configure setuptools to use ``versioningit``'s custom command classes. How to +do this depends on what file you've placed your project's setuptools +configuration in. - from setuptools import setup - from versioningit import get_cmdclasses +- If you're configuring setuptools via :file:`setup.cfg`, you can simply add + the following field to its ``[options]`` table: - setup( - cmdclass=get_cmdclasses(), - # Other arguments go here - ) + .. code:: ini -If you don't need to further customize the build process, this configuration -can be specified via :file:`setup.cfg` instead, like so: + [options] + cmdclass = + sdist = versioningit.cmdclass.sdist + build_py = versioningit.cmdclass.build_py -.. code:: ini +- If you've instead placed all your setuptools configuration in + :file:`pyproject.toml`, then add the following table to it: - [options] - cmdclass = - sdist = versioningit.cmdclass.sdist - build_py = versioningit.cmdclass.build_py + .. code:: toml -.. versionadded:: 2.2.0 + [tool.setuptools.cmdclass] + build_py = "versioningit.cmdclass.build_py" + sdist = "versioningit.cmdclass.sdist" + +- If you're still configuring setuptools through :file:`setup.py`, you'll need + to pass `versioningit.get_cmdclasses()` as the ``cmdclass`` argument to + `setup()`, like so: + + .. code:: python + + from setuptools import setup + from versioningit import get_cmdclasses + + setup( + cmdclass=get_cmdclasses(), + # Other arguments go here + ) + +If you're already using other custom ``build_py`` and/or ``sdist`` command +classes, you'll need to combine them with ``versioningit``'s command classes. +One option is to pass your custom classes to `get_cmdclasses()` in +:file:`setup.py` so that ``versioningit`` will use them as parent classes; see +the function's documentation for more information. If that doesn't work, you +may have to manually modify or subclass your command classes and add a call to +`run_onbuild()` at the appropriate location; see the function's documentation +for more information, but you'll largely be on your own at this point. - ``sdist`` and ``build_py`` classes added for use in :file:`setup.cfg` +Configuring ``onbuild`` +~~~~~~~~~~~~~~~~~~~~~~~ ``versioningit`` provides one ``onbuild`` method, ``"replace-version"`` (the default). It scans a given file for a line matching a given regex and inserts diff --git a/docs/runtime-version.rst b/docs/runtime-version.rst index a0ec9fd..73877e8 100644 --- a/docs/runtime-version.rst +++ b/docs/runtime-version.rst @@ -69,12 +69,11 @@ usually also want to expose that version at runtime, usually via a __version__ = Path(__file__).with_name("VERSION").read_text().strip() 3. *(New in version 1.1.0)* Fill out the ``[tool.versioningit.onbuild]`` - subtable in :file:`pyproject.toml` and configure your :file:`setup.py` or - :file:`setup.cfg` to use ``versioningit``'s custom setuptools commands. - This will allow you to create sdists & wheels in which some file has been - modified to contain the line ``__version__ = ""`` or - similar while leaving your repository alone. See ":ref:`onbuild`" for more - information. + subtable in :file:`pyproject.toml` and configure setuptools to use + ``versioningit``'s custom build commands. This will allow you to create + sdists & wheels in which some file has been modified to contain the line + ``__version__ = ""`` or similar while leaving your + repository alone. See ":ref:`onbuild`" for more information. .. tip::