Expand documentation for ASS subtitles style filtering

docs/source/index.rst

@@ -12,8 +12,10 @@ Main Features
 -------------
 
 - Convert ASS/SSA subtitles to SRT format
+- **Style filtering**: Export only specific subtitle styles
 - Remove effects from subtitle text (optional)
 - Remove and merge consecutive duplicate dialogues (optional)
+- List available styles in ASS files
 - Support for both string paths and Path-like objects
 - Command-line interface (CLI) for easy usage
 
@@ -71,6 +73,19 @@ Here's a basic example of how to use pyasstosrt:
     sub = Subtitle('subtitle.ass')
     sub.export(output_dir='output', encoding='utf-8')
 
+    # Export only default dialogue styles
+    sub = Subtitle('subtitle.ass', only_default_style=True)
+    sub.export()
+
+    # Export specific styles
+    sub = Subtitle('subtitle.ass', include_styles=['Default', 'Alt'])
+    sub.export()
+
+    # List available styles
+    sub = Subtitle('subtitle.ass')
+    styles = sub.get_styles()
+    print(styles)  # ['Default', 'Signs', 'Credits', ...]
+
 Command Line Interface
 --------------------
 
@@ -99,6 +114,18 @@ The library provides a command-line interface for easy usage:
     # Print dialogues to console
     pyasstosrt export subtitle.ass --output-dialogues
 
+    # List available styles
+    pyasstosrt styles subtitle.ass
+
+    # Export only default dialogue styles
+    pyasstosrt export subtitle.ass --only-default
+
+    # Export specific styles
+    pyasstosrt export subtitle.ass --include-styles "Default,Alt"
+
+    # Exclude specific styles
+    pyasstosrt export subtitle.ass --exclude-styles "Signs,Credits"
+
     # Run without installation using uvx
     uvx --from 'pyasstosrt[cli]' pyasstosrt export * --remove-effects --remove-duplicates
 

docs/source/pyasstosrt/cli.rst

@@ -18,17 +18,35 @@ The basic command syntax is:
 
 Where `FILEPATH...` is one or more paths to ASS subtitle files.
 
-Options
--------
+Commands
+--------
+
+``export``
+    Convert ASS/SSA subtitle file(s) to SRT format.
+
+``styles``
+    List all unique styles found in an ASS subtitle file.
+
+Export Options
+--------------
 
-The CLI supports the following options:
+The ``export`` command supports the following options:
 
 ``--remove-effects, -r``
     Remove effects from subtitles.
 
 ``--remove-duplicates, -d``
     Remove duplicate subtitles.
 
+``--only-default, -D``
+    Export only styles containing 'Default' in name (excludes Signs, Credits, etc.).
+
+``--include-styles, -i TEXT``
+    Comma-separated list of style names to include (e.g., 'Default,Signs').
+
+``--exclude-styles, -x TEXT``
+    Comma-separated list of style names to exclude (e.g., 'Signs,Credits_dvd').
+
 ``--output-dir, -o PATH``
     Output directory for the SRT file(s).
 
@@ -41,6 +59,18 @@ The CLI supports the following options:
 ``--version, -v``
     Show version and exit.
 
+.. note::
+   The style filtering options (``--only-default``, ``--include-styles``, ``--exclude-styles``)
+   are mutually exclusive. You can only use one at a time.
+
+Styles Command Options
+----------------------
+
+The ``styles`` command supports the following options:
+
+``--table, -t``
+    Display styles in a formatted table.
+
 Examples
 --------
 
@@ -126,3 +156,73 @@ You can combine multiple options:
 .. code-block:: bash
 
     pyasstosrt export subtitle.ass --remove-effects --remove-duplicates --output-dir ./output
+
+Style Filtering
+--------------
+
+List Available Styles
+~~~~~~~~~~~~~~~~~~~~
+
+Before filtering styles, you can list all available styles in a subtitle file:
+
+.. code-block:: bash
+
+    pyasstosrt styles subtitle.ass
+
+Display styles in a formatted table:
+
+.. code-block:: bash
+
+    pyasstosrt styles subtitle.ass --table
+
+Export Only Default Styles
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Export only dialogue styles (excludes signs, credits, etc.):
+
+.. code-block:: bash
+
+    pyasstosrt export subtitle.ass --only-default
+
+Include Specific Styles
+~~~~~~~~~~~~~~~~~~~~~~
+
+Export only specific styles by name:
+
+.. code-block:: bash
+
+    pyasstosrt export subtitle.ass --include-styles "Default,Alt"
+
+Include multiple styles:
+
+.. code-block:: bash
+
+    pyasstosrt export subtitle.ass --include-styles "Default,Thoughts,Narration"
+
+Exclude Specific Styles
+~~~~~~~~~~~~~~~~~~~~~~
+
+Export all styles except specific ones:
+
+.. code-block:: bash
+
+    pyasstosrt export subtitle.ass --exclude-styles "Signs,Credits"
+
+Exclude multiple styles:
+
+.. code-block:: bash
+
+    pyasstosrt export subtitle.ass --exclude-styles "Signs,Credits_dvd,Opening,Ending"
+
+Combine Style Filtering with Other Options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can combine style filtering with other conversion options:
+
+.. code-block:: bash
+
+    pyasstosrt export subtitle.ass --only-default --remove-effects --remove-duplicates
+
+.. code-block:: bash
+
+    pyasstosrt export subtitle.ass --include-styles "Default,Alt" --output-dir ./output

docs/source/pyasstosrt/subtitle.rst

@@ -18,6 +18,7 @@ Subtitle
       ~Subtitle.convert
       ~Subtitle.export
       ~Subtitle.get_text
+      ~Subtitle.get_styles
       ~Subtitle.remove_duplicates
       ~Subtitle.subtitle_formatting
       ~Subtitle.text_clearing
@@ -35,6 +36,9 @@ Subtitle
       ~Subtitle.dialogues
       ~Subtitle.removing_effects
       ~Subtitle.is_remove_duplicates
+      ~Subtitle.only_default_style
+      ~Subtitle.include_styles
+      ~Subtitle.exclude_styles
 
    .. rubric:: Examples
 
@@ -98,3 +102,88 @@ Advanced Usage
     )
     sub.convert()
     sub.export('output/directory', encoding='utf-8')
+
+Style Filtering
+--------------
+
+List Available Styles
+~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    from pyasstosrt import Subtitle
+
+    # Get list of available styles
+    sub = Subtitle('subtitle.ass')
+    styles = sub.get_styles()
+    print(f"Available styles: {styles}")
+
+Export Only Default Styles
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    from pyasstosrt import Subtitle
+
+    # Export only dialogue styles (excludes signs, credits, etc.)
+    sub = Subtitle('subtitle.ass', only_default_style=True)
+    sub.export()
+
+Include Specific Styles
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    from pyasstosrt import Subtitle
+
+    # Export only specific styles
+    sub = Subtitle('subtitle.ass', include_styles=['Default', 'Alt'])
+    sub.export()
+
+    # Or as a single style
+    sub = Subtitle('subtitle.ass', include_styles=['Default'])
+    sub.export()
+
+Exclude Specific Styles
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    from pyasstosrt import Subtitle
+
+    # Export all styles except specific ones
+    sub = Subtitle('subtitle.ass', exclude_styles=['Signs', 'Credits'])
+    sub.export()
+
+    # Exclude multiple styles
+    sub = Subtitle('subtitle.ass', exclude_styles=['Signs', 'Credits_dvd', 'Opening', 'Ending'])
+    sub.export()
+
+Combine Style Filtering with Other Options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    from pyasstosrt import Subtitle
+
+    # Combine style filtering with effects removal
+    sub = Subtitle(
+        'subtitle.ass',
+        only_default_style=True,
+        removing_effects=True,
+        remove_duplicates=True
+    )
+    sub.export('output')
+
+    # Include specific styles with custom options
+    sub = Subtitle(
+        'subtitle.ass',
+        include_styles=['Default', 'Thoughts'],
+        removing_effects=True
+    )
+    sub.export('output', encoding='utf-8')
+
+.. note::
+   The style filtering options (``only_default_style``, ``include_styles``, ``exclude_styles``)
+   are mutually exclusive. You can only use one at a time. If you try to use multiple,
+   a ``ValueError`` will be raised.