Add all to init

[bendichter]

Fix #1686: Add __all__ to modules

Motivation

Python allows using __all__ to indicate the public interface of a module. This helps users understand what classes and functions are intended to be imported from each module, improves IDE auto-completion, and prevents accidental usage of internal implementation details. This change follows the pattern used by other major packages like scikit-learn.

How to test the behavior?

# Before: dir() shows all module contents including internals
from pynwb import ecephys
print(dir(ecephys))  # Shows everything including __builtins__, etc.

# After: Only public interfaces are imported with *
from pynwb import ecephys
print(ecephys.__all__)  # Shows only intended public interfaces
from pynwb.ecephys import *  # Only imports items listed in __all__

Checklist

[x] Did you update CHANGELOG.md with your changes?
[x] Have you checked our Contributing document?
[x] Have you ensured the PR clearly describes the problem and the solution?
[x] Is your contribution compliant with our coding style? This can be checked running ruff check . && codespell from the source directory.
[x] Have you checked to ensure that there aren't other open Pull Requests for the same change?
[x] Have you included the relevant issue number using "Fix #1686" notation where XXX is the issue number?

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 91.78%. Comparing base (c0ba7e1) to head (3fdef32).

Additional details and impacted files

@@            Coverage Diff             @@
##              dev    #2021      +/-   ##
==========================================
+ Coverage   91.73%   91.78%   +0.04%     
==========================================
  Files          27       27              
  Lines        2722     2738      +16     
  Branches      710      710              
==========================================
+ Hits         2497     2513      +16     
  Misses        149      149              
  Partials       76       76              

Flag	Coverage Δ
integration	73.08% <93.75%> (+0.12%)	⬆️
unit	82.39% <100.00%> (+0.10%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[stephprince]

Looks good to me. Could you add a CHANGELOG update?

And then I think adding the __all__ definitions has caused some issues with the Sphinx documentation:

/home/runner/work/pynwb/pynwb/docs/source/pynwb.testing.icephys_testutils.rst:2: WARNING: more than one target found for cross-reference 'NWBFile': pynwb.NWBFile, pynwb.file.NWBFile [ref.python]

I think one solution would be to update the references to use the more specific path. Could you address those warnings?

[stephprince]

There were still some warnings in the link checker. I took a closer look and I think since the deprecated or private classes (e.g. SweepTable, BaseStorageOverride) were not included in the __all__ definitions, they were no longer being found by sphinx autodoc and so were not being documented:

/home/runner/work/pynwb/pynwb/src/pynwb/file.py:docstring of pynwb.file.NWBFile:78: WARNING: py:class reference target not found: pynwb.icephys.SweepTable [ref.class]

I found this option that we can add to the docs/source/conf.py to solve these warnings, since I believe we still want the documentation for these classes to be accessible on readthedocs even if they are not included in the public interface:

autodoc_default_options = {
    'ignore-module-all': True,
}