From bfdefc8da0be1036f7440904849fd8267e0bf89a Mon Sep 17 00:00:00 2001 From: Jamie Hardt Date: Fri, 18 Nov 2022 12:23:31 -0800 Subject: [PATCH] Documentation --- .readthedocs.yaml | 2 +- README.md | 3 +- docs/requirements.txt | 3 ++ docs/source/for_adr.rst | 114 ++++++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 1 + docs/source/tagging.rst | 12 ++--- 6 files changed, 127 insertions(+), 8 deletions(-) create mode 100644 docs/requirements.txt create mode 100644 docs/source/for_adr.rst diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 764ad2b..9abcda2 100644 --- a/.readthedocs.yaml +++ b/.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 diff --git a/README.md b/README.md index 1776e68..b4c1e5f 100644 --- a/README.md +++ b/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 diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..9d1272d --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,3 @@ +sphinx==4.2.0 +sphinx_rtd_theme==1.0.0 +readthedocs-sphinx-search==0.1.1 diff --git a/docs/source/for_adr.rst b/docs/source/for_adr.rst new file mode 100644 index 0000000..ed41684 --- /dev/null +++ b/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. diff --git a/docs/source/index.rst b/docs/source/index.rst index 9250eba..c9fdd0b 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -12,6 +12,7 @@ Welcome to ptulsconv's documentation! quickstart tagging + for_adr Indices and tables ================== diff --git a/docs/source/tagging.rst b/docs/source/tagging.rst index c0178e8..34f8ca9 100644 --- a/docs/source/tagging.rst +++ b/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: