sage -fixdistributions

src/bin/sage

@@ -482,10 +482,13 @@ usage_advanced() {
         echo "  --fixdoctests file.py"
         echo "                      -- Run doctests and replace output of failing doctests"
         echo "                         with actual output."
-        echo "  --fiximports <files|dir>"
+        echo "  --fiximports <files|dirs>"
         echo "                      -- Replace imports from sage.PAC.KAGE.all by specific"
         echo "                         imports when sage.PAC.KAGE is an implicit namespace"
         echo "                         package"
+        echo "  --fixdistributions <files|dirs>"
+        echo "                      -- Check or update '# sage_setup: distribution'"
+        echo "                         directives in source files"
     fi
     echo "  --sh [...]         -- run a shell with Sage environment variables"
     echo "                        as they are set in the runtime of Sage"
@@ -986,6 +989,11 @@ if [ "$1" = '-fiximports' -o "$1" = '--fiximports' ]; then
     exec sage-python -m sage.misc.replace_dot_all "$@"
 fi
 
+if [ "$1" = '-fixdistributions' -o "$1" = '--fixdistributions' ]; then
+    shift
+    exec sage-python -m sage.misc.package_dir "$@"
+fi
+
 if [ "$1" = '-tox' -o "$1" = '--tox' ]; then
     shift
     if [ -n "$SAGE_SRC" -a -f "$SAGE_SRC/tox.ini" ]; then

src/doc/en/developer/packaging_sage_library.rst

@@ -146,6 +146,34 @@ The source directory of a distribution package, such as
   controls which files and directories of the
   monolithic Sage library source tree are included in the distribution
 
+  The manifest should be kept in sync with the directives of the form
+  ``# sage_setup: distribution = sagemath-polyhedra`` at the top of
+  source files.  Sage provides a tool ``sage --fixdistributions``
+  that assists with this task. For example::
+
+    $ ./sage --fixdistributions --set sagemath-polyhedra \
+         src/sage/geometry/polyhedron/base*.py
+
+  adds or updates the directives in the specified files; and::
+
+    $ ./sage --fixdistributions --add sagemath-polyhedra \
+         src/sage/geometry/polyhedron
+
+  adds the directive to all files in the given directory that do not
+  include a directive yet.
+
+  After a distribution has been built (for example, by the command
+  ``make pypi-wheels``) or at least an sdist has been built (for
+  example, by the command ``make sagemath_polyhedra-sdist``), the
+  distribution directives in all files in the source distribution
+  can be updated using the switch ``--from--egg-info``::
+
+    $ ./sage --fixdistributions --set sagemath-polyhedra --from-egg-info
+
+  To take care of all distributions, use::
+
+    $ ./sage --fixdistributions --set all --from-egg-info
+
 - `pyproject.toml <https://pip.pypa.io/en/stable/reference/build-system/pyproject-toml/>`_,
   `setup.cfg <https://setuptools.pypa.io/en/latest/userguide/declarative_config.html>`_,
   and `requirements.txt <https://pip.pypa.io/en/stable/user_guide/#requirements-files>`_ --