From 3fc44b1449b767e9e935ec1cf521db483b277fe7 Mon Sep 17 00:00:00 2001 From: Thomas Kluyver Date: Fri, 27 Jan 2023 18:18:55 +0000 Subject: [PATCH] Document what is included in sdist --- doc/pyproject_toml.rst | 32 ++++++++++++++++++++++---------- flit/__init__.py | 2 +- 2 files changed, 23 insertions(+), 11 deletions(-) diff --git a/doc/pyproject_toml.rst b/doc/pyproject_toml.rst index 18d1d26d..9d4f9da1 100644 --- a/doc/pyproject_toml.rst +++ b/doc/pyproject_toml.rst @@ -400,10 +400,13 @@ Sdist section .. versionadded:: 2.0 -When you use :ref:`build_cmd` or :ref:`publish_cmd`, Flit builds an sdist -(source distribution) tarball containing the files that are checked into version -control (git or mercurial). If you want more control, or it doesn't recognise -your version control system, you can give lists of paths or glob patterns as +With no configuration, Flit can make an sdist with everything it needs +to build and install your module: the package contents (including non-Python +data files, but not ``.pyc`` bytecode files), your ``pyproject.toml`` file, +the readme & license files given in the metadata, and the :ref:`external data +folder ` if you specified that. + +If you want more control, you can give lists of paths or glob patterns as ``include`` and ``exclude`` in this section. For example: .. code-block:: toml @@ -429,13 +432,22 @@ These paths: Exclusions have priority over inclusions. Bytecode is excluded by default and cannot be included. -.. note:: +Including files committed in git/hg +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you use :ref:`build_cmd` or :ref:`publish_cmd`, you can also make sdists with +the files which are committed in version control (git or hg). This is a shortcut +to e.g. include documentation source files, but not built HTML or PDF +documentation. The include and exclude patterns are then applied on top of this +list. + +For now, including files from version control is the default for :ref:`build_cmd` +and :ref:`publish_cmd`, and can be disabled with ``--no-use-vcs``. The default +will switch in a future version. - If you are not using :ref:`build_cmd` but ``flit_core`` via another build - frontend, Flit doesn't doesn't check the VCS for files to include but instead - builds a 'minimal' sdist (which includes the files necessary to build a wheel). - You'll have to adapt your inclusion/exclusion rules to achieve the same result - as you'd get with :ref:`build_cmd`. +Using ``flit_core`` as a backend to other tools such as `build +`_ never gets the list of files +for the sdist from version control. .. _pyproject_toml_external_data: diff --git a/flit/__init__.py b/flit/__init__.py index cc16486a..9d881446 100644 --- a/flit/__init__.py +++ b/flit/__init__.py @@ -92,7 +92,7 @@ def add_shared_build_options(parser: argparse.ArgumentParser): vcs_grp = parser.add_mutually_exclusive_group() vcs_grp.add_argument('--use-vcs', action='store_true', - help=("Get the list of files to include in the sdist from git or hg. " + help=("Choose which files to include in the sdist using git or hg. " "This is a convenient way to include all checked-in files, like " "tests and doc source files, in your sdist, but requires that git " "or hg is available on the command line. This is currently the "