sagemathgh-36135: sage -fixdistributions

    
<!-- ^^^^^
Please provide a concise, informative and self-explanatory title.
Don't put issue numbers in there, do this in the PR body below.
For example, instead of "Fixes sagemath#1234" use "Introduce new method to
calculate 1+1"
-->
<!-- Describe your changes here in detail -->
This is a new maintenance command for adding/updating `# sage_setup:
distribution` directives at the top of source files.

Based on a discussion in
sagemath#35884 (comment)

<!-- Why is this change required? What problem does it solve? -->
<!-- If this PR resolves an open issue, please link to it here. For
example "Fixes sagemath#12345". -->
- Part of: sagemath#29705
- Cherry-picked from: sagemath#35095
<!-- If your change requires a documentation PR, please link it
appropriately. -->

### 📝 Checklist

<!-- Put an `x` in all the boxes that apply. -->
<!-- If your change requires a documentation PR, please link it
appropriately -->
<!-- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->
<!-- Feel free to remove irrelevant items. -->

- [x] The title is concise, informative, and self-explanatory.
- [x] The description explains in detail what this PR is about.
- [ ] I have linked a relevant issue or discussion.
- [ ] I have created tests covering the changes.
- [ ] I have updated the documentation accordingly.

### ⌛ Dependencies

<!-- List all open PRs that this PR logically depends on
- sagemath#12345: short description why this is a dependency
- sagemath#34567: ...
-->
- Depends on sagemath#36533 (CI fix)

<!-- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->
    
URL: sagemath#36135
Reported by: Matthias Köppe
Reviewer(s): Kwankyu Lee, Matthias Köppe

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>`_ --