docs: improve NumPy-style docstrings in video module

[AlgoFoe]

Description

What is this PR

• Bug fix
• Addition of a new feature
• Other

Why is this PR needed?

• The codebase lacked consistent docstrings, making Sphinx autodoc output incomplete and hard to read.

What does this PR do?

• Adds/updates NumPy-style docstrings (module, class, method, function level) in video.py.

References

• Part of Issue-96

How has this PR been tested?

• No functional changes, existing tests pass.

Is this a breaking change?

• No.

Does this PR require an update to the documentation?

• Yes.

Checklist:

• The code has been tested locally
• Tests have been added to cover all new functionality (unit & integration)
• The documentation has been updated to reflect any changes
• The code has been formatted with pre-commit

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.45%. Comparing base (9251a52) to head (fa844f0).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #457      +/-   ##
==========================================
+ Coverage   89.43%   89.45%   +0.02%     
==========================================
  Files          27       27              
  Lines        1287     1290       +3     
==========================================
+ Hits         1151     1154       +3     
  Misses        136      136              

☔ View full report in Codecov by Harness.
📢 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.

[IgorTatarnikov]

I don't think this type communicates exactly what the function requires.

Based on the code below it will always be passed a Scene, int, int, bool, followed by optional arguments. This is not communicated well with this type.

We could create a custom type using Protocol as a base type that strictly defines the function parameters. Not sure if the added complexity is worth it here though, do you have any thoughts to add @alessandrofelder?

[alessandrofelder]

Following discussion in our meeting, let's make this a FrameGenerator deriving from Protocol.

[IgorTatarnikov]

This looks good to me, I just have a slight comment regarding how the Callable types are described.

I think we should be more specific, as the code expects a certain number and position of arguments.

[IgorTatarnikov]

Similar to above, I think this function could be typed better, especially as there are 3 required arguments.