allign manifest.in to template

Author: HGWright

MANIFEST.in

@@ -1,12 +1,70 @@
-prune .github
+# NOTE: based on a generic template in Scitools/.github/templates/MANIFEST.in
+
+# General principles
+#     - enable user to build locally, as well as in CI
+#     - make it ignore temporary files generated by dev processes, e.g. coverage checks
+#     - encode typical decisions, e.g. whether we package docs, requirements etc
+
+#---------
+# SECTION: main code sources
+#
+recursive-include src *.py *.pyx
+    # principles:
+    #    - *no* "prune" command is used
+    #    - use "include-recursive", by relevant file extensions
+    # hints:
+    #     - top-level dir is typically "src", but maybe "lib" or <package-name>
+    #     - default package rules mean we generally don't actually *need* a statement
+    #         - but it's better to be explicit
+    #     - extension filetypes are typically sources (*.py)
+    #         - might also need testdata files, e.g. *.nc, *.npy *.npz
+    #         - also possibly non-python, e.g. *.pyx for Cython
+
+#---------
+# SECTION: requirements
 prune requirements
 recursive-include requirements *.txt
-recursive-include src *.py *.pyx
-include CITATION.cff
+    # principles:
+    #    include just requirements-level info, not lock files
+    # hints:
+    #    - not all projects include requirements, but they can be drawn in anyway by dynamic dependencies
+    #        in the setuptools build process, linked via config in pyproject.toml
+    #    - for some repos, the *.txt are actually lockfiles.  This probably needs fixing.
+
+#---------
+# SECTION: root files
 exclude .flake8
 exclude .gitignore
 exclude .pre-commit-config.yaml
+include CITATION.cff
+include LICENSE
+    # principles:
+    #    - *ANY* file in the root should be explicitly "include"- or "exclude"-d
+    #         - EXCEPT (possibly) those covered by setuptools default rules (see above link)
+    #             - including : README.md/.rst; pyproject.toml; setup.py/.cfg
+    #         - N.B. a GHA "ci-manifest" check, if used, will check all this
+    #    - the above are typical ones : given in sorted order
+    #    - NB many will (eventually) be templated, but that is a separate issue
+    #    - probably, this section can be included as *boilerplate*
+    #        - i.e. it doesn't matter if some of the files mentioned don't exist
+
+#---------
+# SECTION: generic exclusions
+# (1) top-level directories to omit entirely
+prune .github
+# (2) top-level files to omit
 exclude Dockerfile
 exclude codecov.yml
 exclude index.ipynb
 exclude summary.png
+# (3) file types (path patterns) to skip everywhere
+global-exclude *.py[cod]
+global-exclude __pycache__
+    # principles:
+    #    - common directories, files and file-types to be generally ignored
+    #        - all outside version control, temporary non-coding output and cache data
+    #             produced by dev processes, automation or user tools
+    #    - by having this section LAST, it can remove files which might have been added by
+    #        previous sections -- such as python compiler cache files
+    #    - can include this section as **boilerplate** :
+    #        - won't all exist in every repo, but including them all does no harm