Hypnogram: add pad method and doc improvements

[raphaelvallat]

Hypnogram.pad(before, after, fill_value)

Extends the hypnogram by prepending and/or appending epochs. The padding length can be specified as an integer number of epochs or as an absolute timestamp (requires start to be set). A UserWarning is raised when a timestamp-based duration is not a perfect multiple of freq, and the count is silently floored to the nearest complete epoch.

fill_value accepts:

• a single stage label such as "UNS" (default) or "WAKE", applied to both ends
• "edge", to repeat the first/last epoch value on the respective end (analogous to numpy.pad with mode="edge")
• a 2-tuple (fill_before, fill_after) to set a different fill stage for each end

hyp.pad(before=2, after=1)                          # pad both ends with UNS
hyp.pad(before=2, after=1, fill_value="edge")       # repeat edge epochs
hyp.pad(before=1, after=2, fill_value=("UNS", "WAKE"))  # different fill per end

# timestamp-based: align to a fixed recording window
hyp.pad(before="2023-01-01 22:00:00", after="2023-01-01 23:00:00")

Documentation

• The Hypnogram class docstring now opens with the three structural assumptions the class relies on (uniform epoch duration, contiguous recording, closed stage vocabulary).
• A summary table of the main methods has been added to the class docstring for quick reference.
• The redundant Attributes section has been removed from the class docstring; attributes are now documented solely through their individual @property docstrings, eliminating duplication in the Sphinx output.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 93.26923% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 85.68%. Comparing base (8666d3d) to head (65d0ee7).
⚠️ Report is 3 commits behind head on master.

Files with missing lines	Patch %	Lines
src/yasa/hypno.py	93.26%	3 Missing and 4 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #232      +/-   ##
==========================================
+ Coverage   85.58%   85.68%   +0.09%     
==========================================
  Files          14       14              
  Lines        2845     2906      +61     
  Branches      364      384      +20     
==========================================
+ Hits         2435     2490      +55     
- Misses        351      354       +3     
- Partials       59       62       +3     

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.