Update docstrings and enable ruff D rules

pyproject.toml

@@ -71,9 +71,10 @@ quote-style = 'single'  # Prefer single quotes, except for triple quotes strings
 [tool.ruff.lint]
 select = ['ALL']  # https://docs.astral.sh/ruff/rules/
 ignore = [
-    'ANN101',  # No need to add type to self
     'CPY001',  # Do not require copyright notices
-    'D',  # Ignore docstring checks
+    'D104',  # Allow missing package docstring
+    'D203',  # Should instead be no blank line before class docstring
+    'D213',  # Summary should instead be on the first line
     'EM',  # Allow messages directly in exceptions
     'FBT001',  # Allow positional for boolean arguments
     'FBT002',  # Allow default value for boolean arguments

time_lapse/cli.py

@@ -1,3 +1,4 @@
+"""Function called by the CLI."""
 import argparse
 
 from time_lapse import output, source
@@ -14,11 +15,26 @@ def make_movie(
     dryrun: bool,
     filters: list[tuple[str, dict[str, str]]] | None = None,
 ) -> None:
+    """Detect which movie files have an audio stream steered via the CLI.
+
+    :param name: Output name of the movie, without file extension.
+    :param patterns: Glob pattern(s) with which to find the input frames.
+    :param fps: Frame rate of the created movie.
+    :param deflicker: Frame window to use for deflicker, off when set to 0..
+    :param watermark: Enable or disable watermark. For custom watermark provide two
+        values, one main text and the subtext.
+    :param verbose: When enabled the output is more verbose, showing the ffmpeg
+        command and the filter graph.
+    :param dryrun: When enabled the ffmpeg command is not actually executed.
+    :param filters: A list of additional filters to apply to the movie.
+
+    """
     source_input = source.get_input(patterns, fps, deflicker, filters)
     output.create_outputs(source_input, name, watermark=watermark, verbose=verbose, dryrun=dryrun)
 
 
 def get_parser_timelapse() -> argparse.ArgumentParser:
+    """Get argument parser for the timelapse cli."""
     parser = argparse.ArgumentParser(description='Combine frames into a movie.')
     parser.add_argument(
         '--name',
@@ -58,20 +74,22 @@ def get_parser_timelapse() -> argparse.ArgumentParser:
     )
     parser.add_argument(
         '--watermark',
-        help='Add watermark, provide two value, one main text and the subtext.',
+        help='Add watermark, provide two values, one main text and the subtext.',
         nargs=2,
     )
     return parser
 
 
 def timelapse() -> None:
+    """Create a movie steered via the CLI."""
     parser = get_parser_timelapse()
     kwargs = vars(parser.parse_args())
 
     make_movie(**kwargs)
 
 
 def get_parser_detect_audio() -> argparse.ArgumentParser:
+    """Get argument parser for the detect_audio cli."""
     parser = argparse.ArgumentParser(description='Find movie files with audio streams.')
     parser.add_argument(
         '--pattern',
@@ -82,6 +100,7 @@ def get_parser_detect_audio() -> argparse.ArgumentParser:
 
 
 def detect_audio() -> None:
+    """Detect which movie files have an audio stream steered via the CLI."""
     parser = get_parser_detect_audio()
     kwargs = vars(parser.parse_args())
 

time_lapse/detect_audio.py

@@ -1,10 +1,17 @@
+"""Function related to detecting audio in movies."""
 from collections.abc import Iterator
 from pathlib import Path
 
 import ffmpeg
 
 
 def files_with_audio(pattern: str = '*.mp4') -> Iterator[str]:
+    """Find files matching the provided pattern with an audio stream.
+
+    :param pattern: glob pattern to find files to check.
+    :returns: Iterator over the found files with an audio stream.
+
+    """
     for filename in Path().glob(pattern):
         if any(
             stream['codec_type'] == 'audio'

time_lapse/output.py

@@ -1,3 +1,4 @@
+"""Functions related to creating the output."""
 import ffmpeg
 
 from .watermark import add_watermark
@@ -18,7 +19,7 @@ def create_outputs(
     verbose: bool = False,
     dryrun: bool = False,
 ) -> ffmpeg.nodes.OutputNode:
-    """Create output at multiple sizes (FHD and qHD)
+    """Create output at multiple sizes (FHD and qHD).
 
     :param source_input: ffmpeg input node ready for scaling and conversion.
     :param name: name of the output.
@@ -28,7 +29,6 @@ def create_outputs(
     :param dryrun: if True the command will not be run.
 
     """
-
     fhd_input = source_input.filter_('scale', size='1920x1920', force_original_aspect_ratio='decrease')
 
     if watermark:

time_lapse/source.py

@@ -1,3 +1,4 @@
+"""Function related to finding the input."""
 import ffmpeg
 
 
@@ -7,7 +8,7 @@ def get_input(
     deflicker: int,
     filters: list[tuple[str, dict[str, str]]] | None,
 ) -> ffmpeg.nodes.FilterNode:
-    """Find input files and set framerate and deflickering
+    """Find input files and set framerate and deflickering.
 
     :param patterns: glob pattern(s) to find input frames.
     :param fps: framerate of the output video.

time_lapse/thumbnail.py

@@ -1,3 +1,4 @@
+"""Function related to creating thumbnails."""
 import pathlib
 import shutil
 
@@ -10,6 +11,17 @@ def create_thumbnail(
     width: int = 180,
     height: int = 120,
 ) -> None:
+    """Create a thumbnail of the desired size for a given source image.
+
+    The image will be cropped if the target aspect ratio does not
+    match the aspect ratio of the source image.
+
+    :param name: Name of the output thumbnail file.
+    :param poster_path: Path to the source image.
+    :param width: Target pixel width of the thumbnail.
+    :param height: Target pixel height of the thumbnail.
+
+    """
     target_path = pathlib.Path() / f'{name}{poster_path.suffix}'
     thumbnail_path = target_path.parent / f'{name}@2x.png'
 

time_lapse/watermark.py

@@ -1,3 +1,4 @@
+"""Function related to adding and configuring watermarks."""
 import pathlib
 
 import ffmpeg
@@ -18,6 +19,17 @@ def add_watermark(
     subtext: str,
     fontsize: int = 32,
 ) -> ffmpeg.nodes.FilterNode:
+    """Add a text-based watermark to the video.
+
+    Add text to the bottom right of the video,
+    using the Jost font in white with a black shadow.
+
+    :param input_node: An ffmpeg source node.
+    :param text: Main watermark text.
+    :param subtext: Second row of text with smaller font size.
+    :param fontsize: Font size of the main text, the subtext will be 5/8th the size.
+
+    """
     watermarked_input = input_node.drawtext(
         text=text,
         fontsize=fontsize,