Documentation

docs/source/dev/classes.rst

@@ -4,5 +4,6 @@ ptulsconv Classes
 Docparser Classes
 -----------------
 
-.. automodule:: ptulsconv.docparser.adr_entity
-    :members:
+.. autoclass:: ptulsconv.docparser.adr_entity.ADRLine
+    :members:
+    :undoc-members:

docs/source/dev/modules.rst

@@ -1,12 +1,18 @@
-ptulsconv Modules
-=================
+ptulsconv Auxiliary and Helper Modules
+======================================
+
+Commands Module
+---------------
+
+.. automodule:: ptulsconv.commands
+    :members:
+
 
 Broadcast Timecode Module
 -------------------------
 
 .. automodule:: ptulsconv.broadcast_timecode
     :members:
-    :undoc-members:
 
 
 Footage Module
@@ -14,12 +20,19 @@ Footage Module
 
 .. automodule:: ptulsconv.footage
     :members:
-    :undoc-members:
+
+
+Reporting Module
+----------------
 
 .. automodule:: ptulsconv.reporting
     :members:
     :undoc-members:
 
+
+Validations Module
+------------------
+
 .. automodule:: ptulsconv.validations
     :members:
     :undoc-members:

ptulsconv/broadcast_timecode.py

@@ -1,6 +1,4 @@
 """
-broadcast_timecode.py
-
 Useful functions for parsing and working with timecode.
 """
 

ptulsconv/commands.py

@@ -1,3 +1,7 @@
+"""
+This module provides the main implementation of input document
+parsing and transformation.
+"""
 import datetime
 import os
 

ptulsconv/docparser/__init__.py

@@ -1 +1,5 @@
+"""
+Docparser module
+"""
+
 from .doc_parser_visitor import parse_document

ptulsconv/docparser/adr_entity.py

@@ -1,3 +1,8 @@
+"""
+This module defines classes and methods for converting :class:`Event` objects into 
+:class:`ADRLine` objects.
+"""
+
 from ptulsconv.docparser.tag_compiler import Event
 from typing import Optional, List, Tuple 
 from dataclasses import dataclass
@@ -7,6 +12,15 @@ from ptulsconv.docparser.tag_mapping import TagMapping
 
 
 def make_entities(from_events: List[Event]) -> Tuple[List['GenericEvent'], List['ADRLine']]:
+    """
+    Accepts a list of Events and converts them into either ADRLine events or
+    GenricEvents by calling :func:`make_entity` on each member.
+
+    :param from_events: A list of `Event` objects.
+
+    :returns: A tuple of two lists, the first containing :class:`GenericEvent` and the 
+        second containing :class:`ADRLine`.
+    """
     generic_events = list()
     adr_lines = list()
 
@@ -21,6 +35,14 @@ def make_entities(from_events: List[Event]) -> Tuple[List['GenericEvent'], List[
 
 
 def make_entity(from_event: Event) -> Optional[object]:
+    """
+    Accepts an event and creates either an :class:`ADRLine` or a 
+    :class:`GenericEvent`. An event is an "ADRLine" if it has a cue number/"QN"
+    tag field.
+
+    :param from_event:  An :class:`Event`.
+
+    """
     instance = GenericEvent
     tag_map = GenericEvent.tag_mapping
     if 'QN' in from_event.tags.keys():
@@ -67,6 +89,7 @@ class GenericEvent:
 
 @dataclass
 class ADRLine(GenericEvent):
+    
     priority: Optional[int] = None
     cue_number: Optional[str] = None
     character_id: Optional[str] = None
@@ -109,30 +132,4 @@ class ADRLine(GenericEvent):
                    formatter=(lambda x: len(x) > 0))
     ]
 
-    # def __init__(self):
-    #     self.title = None
-    #     self.supervisor = None
-    #     self.client = None
-    #     self.scene = None
-    #     self.version = None
-    #     self.reel = None
-    #     self.start = None
-    #     self.finish = None
-    #     self.priority = None
-    #     self.cue_number = None
-    #     self.character_id = None
-    #     self.character_name = None
-    #     self.actor_name = None
-    #     self.prompt = None
-    #     self.reason = None
-    #     self.requested_by = None
-    #     self.time_budget_mins = None
-    #     self.note = None
-    #     self.spot = None
-    #     self.shot = None
-    #     self.effort = False
-    #     self.tv = False
-    #     self.tbw = False
-    #     self.omitted = False
-    #     self.adlib = False
-    #     self.optional = False
+

ptulsconv/footage.py

@@ -1,8 +1,20 @@
+"""
+Methods for converting string reprentations of film footage.
+"""
 from fractions import Fraction
 import re
 from typing import Optional
 
+
 def footage_to_seconds(footage: str) -> Optional[Fraction]:
+    """
+    Converts a string representation of a footage (35mm, 24fps) 
+    into a :class:`Fraction`, this fraction being a some number of 
+    seconds.
+
+    :param footage: A string reprenentation of a footage of the form
+        resembling "90+01".
+    """
     m = re.match(r'(\d+)\+(\d+)(\.\d+)?', footage)
     if m is None:
         return None

ptulsconv/reporting.py

@@ -1,3 +1,9 @@
+"""
+Reporting logic. These methods provide reporting methods to the package and
+take some pains to provide nice-looking escape codes if we're writing to a
+tty.
+"""
+
 import sys
 
 

ptulsconv/validations.py

@@ -1,3 +1,7 @@
+"""
+Validation logic for enforcing various consistency rules.
+"""
+
 from dataclasses import dataclass
 from ptulsconv.docparser.adr_entity import ADRLine
 from typing import Iterator, Optional