Align manifest to template

MANIFEST.in

@@ -1,20 +1,105 @@
-prune .github
+# A generic template for "MANIFEST.in" files in Scitools repos.
+# NOTE: most of this can't be duplicated as-is into any given repo, but suggests
+#     guidelines + structure.
+# For the syntax of "MANIFEST.in" files, see:
+#     https://setuptools.pypa.io/en/latest/userguide/miscellaneous.html#using-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 tephi *.py *.json *.npz *.txt
+    # 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: docs
+prune docs
+# and if required ... include ONLY docs source files.
+# E.G. recursive-include docs *.rst *.inc
+    # principles:
+    #    - use prune to ignore everything (optionally: except the docs sources)
+    # hints:
+    #    - most projects don't want to package the docs, but some currently do (cf-units).
+
+
+#---------
+# SECTION: requirements
+prune requirements
+recursive-include requirements *.yml
+    # 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 .git-blame-ignore-revs
+exclude .git_archival.txt
+exclude .gitattributes
+exclude .gitignore
+exclude .lycheeignore
+exclude .mailmap
+exclude .pre-commit-config.yaml
+exclude .readthedocs.yml
+exclude .ruff.toml
+exclude CHANGES
+include CITATION.cff
+exclude CODE_OF_CONDUCT.md
+include COPYING
+include COPYING.LESSER
+include environment.yml
 include LICENSE
-include *.ipynb
-include *.yaml
-include *.yml
-include *.cff
-include .coveragerc
-include .flake8
-include .git-blame-ignore-revs
+exclude Makefile
+exclude codecov.yml
+include noxfile.py
 include tox.ini
-recursive-include requirements *.yml
-recursive-include docs *.bat
-recursive-include docs *.ico
-recursive-include docs *.png
-recursive-include docs *.py
-recursive-include docs *.rst
-recursive-include docs Makefile
-recursive-include tephi *.json
-recursive-include tephi *.npz
-recursive-include tephi *.txt
+    # 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
+prune .nox
+prune .tox
+prune .coverage
+# (2) top-level files to omit
+exclude .coveragerc
+exclude index.ipynb
+# (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