Documentation

.readthedocs.yaml

@@ -26,4 +26,4 @@ formats:
 #Optionally declare the Python requirements required to build your docs
 python:
    install:
-   - requirements: requirements.txt
+   - requirements: docs/requirements.txt

README.md

@@ -14,7 +14,7 @@ Read Pro Tools text exports and generate PDF reports, JSON output.
 
 ## Quick Start
 
-For a quick overview of how to cue ADR with `ptulsconv`, check out the [Quickstart](docs/QUICKSTART.rst).
+For a quick overview of how to cue ADR with `ptulsconv`, check out the [Quickstart][quickstart].
 
 
 ## Installation
@@ -41,5 +41,6 @@ reporting, and supplemental JSON documents can be output for use with other
 workflows.
 
 [avp]: http://www.avid.com/pro-tools
+[quickstart]: https://ptulsconv.readthedocs.io/en/latest/quickstart.html
 
 

docs/requirements.txt

@@ -0,0 +1,3 @@
+sphinx==4.2.0
+sphinx_rtd_theme==1.0.0
+readthedocs-sphinx-search==0.1.1

docs/source/for_adr.rst

@@ -0,0 +1,114 @@
+For ADR Report Generation
+=========================
+
+Reports Created by the ADR Report Generator
+-------------------------------------------
+
+(FIXME: write this)
+
+
+Tags Used by the ADR Report Generator
+-------------------------------------
+
+
+Project-Level Tags
+""""""""""""""""""
+
+It usually makes sense to place these either in the session name,
+or on a marker at the beginning of the session, so it will apply to
+all of the clips in the session.
+
+``Title``:
+    The title of the project. This will appear at the top
+    of every report.
+
+``Supv``:
+    The supervisor of the project. This appears at the bottom
+    of every report.
+
+``Client``:
+    The client of the project. This will often appear under the
+    title on every report.
+
+``Spot``: The date or version number of the spotting report.
+
+
+Time Range Tags
+"""""""""""""""
+
+All of these tags can be set to different values on each clip, but
+it often makes sense to use these tags in a time range.
+
+``Sc``:
+    The scene description. This appears on the continuity report
+    and is used in the Director's logs.
+
+``Ver``:
+    The picture version. This appears beside the spot timecodes
+    on most reports.
+
+``Reel``: The reel. This appears beside the spot timecodes
+    on most reports and is used to summarize line totals on the
+    line count report.
+
+
+Line tags
+"""""""""
+
+``P``: 
+    Priority.
+
+``QN``: 
+    Cue number. This appears on all reports and `ptulsconv` 
+    verify that all cues in a given report have unique cue numbers.
+
+``CN``: 
+    Character number. This is used to collate character records
+    and will appear on the line count and in character-collated 
+    reports.
+
+``Char``: 
+    Character name. By default, a clip will set this to the 
+    name of the track it appears on, but the track name can be
+    overridden here.
+
+``Actor``: 
+    Actor name.
+
+``Line``: 
+    The prompt to appear for this ADR line. By default, this
+    will be whatever text appears in a clip name prior to the first
+    tag.
+
+``R``: 
+    Reason.
+
+``Mins``: 
+    Time budget for this line, in minutes. This is used in the
+    line count report to give estimated times for each character. This 
+    can be set for the entire project (with a marker), or for individual 
+    actors (with a tag in the track comments), or can be set for 
+    individual lines to override these. 
+
+``Shot``: 
+    Shot. A Date or other description indicating the line has been
+    recorded.
+
+
+Boolean-valued ADR Tag Fields
+"""""""""""""""""""""""""""""
+
+``EFF``: 
+    Effort. Lines with this tag are subtotaled in the line count report.
+
+``TV``: 
+    TV line. Lines with this tag are subtotaled in the line count report.
+
+``TBW``: 
+    To be written.
+
+``ADLIB``:
+    Ad-lib.
+
+``OPT``: 
+    Optional. Lines with this tag are subtotaled in the line count report.

docs/source/index.rst

@@ -12,6 +12,7 @@ Welcome to ptulsconv's documentation!
 
    quickstart
    tagging
+   for_adr
 
 Indices and tables
 ==================

docs/source/tagging.rst

@@ -10,9 +10,9 @@ Fields in Clip Names
 
 Track names, track comments, and clip names can also contain meta-tags, or 
 "fields," to add additional columns to the output. Thus, if a clip has the 
-name:
+name:::
 
-`Fireworks explosion {note=Replace for final} $V=1 [FX] [DESIGN]`
+    `Fireworks explosion {note=Replace for final} $V=1 [FX] [DESIGN]`
 
 The row output for this clip will contain columns for the values:
 
@@ -32,13 +32,13 @@ in this case may contain spaces or any chartacter up to the closing bracket.
 to create a boolean-valued field; in the output, clips with the field 
 will have it, and clips without will have the column with an empty value.
 
-For example, if three clips are named:
+For example, if three clips are named:::
 
-`"Squad fifty-one, what is your status?" [FUTZ] {Ch=Dispatcher} [ADR]`
+    `"Squad fifty-one, what is your status?" [FUTZ] {Ch=Dispatcher} [ADR]`
 
-`"We are ten-eight at Rampart Hospital." {Ch=Gage} [ADR]`
+    `"We are ten-eight at Rampart Hospital." {Ch=Gage} [ADR]`
 
-`(1M) FC callouts rescuing trapped survivors. {Ch=Group} $QN=1001 [GROUP]`
+    `(1M) FC callouts rescuing trapped survivors. {Ch=Group} $QN=1001 [GROUP]`
 
 The output will contain the range: