Restructuring documenation

Swiching to readthedocs.io

.readthedocs.yaml

@@ -0,0 +1,29 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.10"
+    # You can also specify other tool versions:
+    # nodejs: "16"
+    # rust: "1.55"
+    # golang: "1.17"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: docs/source/conf.py
+
+#If using Sphinx, optionally build your docs in additional formats such as PDF
+formats:
+   - pdf
+
+#Optionally declare the Python requirements required to build your docs
+python:
+   install:
+   - requirements: requirements.txt

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "esbonio.sphinx.confDir": ""
+}

README.md

@@ -1,3 +1,4 @@
+[![Documentation Status](https://readthedocs.org/projects/ptulsconv/badge/?version=latest)](https://ptulsconv.readthedocs.io/en/latest/?badge=latest)
 ![](https://img.shields.io/github/license/iluvcapra/ptulsconv.svg)
 ![](https://img.shields.io/pypi/pyversions/ptulsconv.svg) 
 [![](https://img.shields.io/pypi/v/ptulsconv.svg)][pypi]
@@ -12,7 +13,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](doc/QUICKSTART.md).
+For a quick overview of how to cue ADR with `ptulsconv`, check out the [Quickstart](docs/QUICKSTART.rst).
 
 
 ## Installation

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/source/conf.py

@@ -0,0 +1,69 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'ptulsconv'
+copyright = '2022, Jamie Hardt'
+author = 'Jamie Hardt'
+release = 'Version 2'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.todo',
+    'sphinx.ext.coverage',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.githubpages',
+]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+master_doc = 'index'
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+
+
+
+latex_documents = [
+    (master_doc, 'ptulsconv.tex', u'ptulsconv Documentation',
+     u'Jamie Hardt', 'manual'),
+]
+
+
+# -- Options for Epub output -------------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = project
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#
+# epub_identifier = ''
+
+# A unique identification for the text.
+#
+# epub_uid = ''
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files = ['search.html']
+
+
+# -- Extension configuration -------------------------------------------------
+
+# -- Options for todo extension ----------------------------------------------
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True

docs/source/index.rst

@@ -0,0 +1,21 @@
+.. ptulsconv documentation master file, created by
+   sphinx-quickstart on Fri Nov 18 10:40:33 2022.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to ptulsconv's documentation!
+=====================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   quickstart
+   tagging
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/source/quickstart.rst

@@ -1,32 +1,40 @@
-# Quick Start for ADR Spotting and Reporting with `ptulsconv`
+Quick Start
+===========
 
-## Step 1: Use Pro Tools to spot ADR Lines
+The workflow for creating ADR reports in `ptulsconv` is similar to other ADR 
+spotting programs: spot ADR lines in Pro Tools with clips using a special 
+code to take notes, export the tracks as text and then run the program.
+
+
+Step 1: Use Pro Tools to Spot ADR Lines
+---------------------------------------
 
 `ptulsconv` can be used to spot ADR lines similarly to other programs.
 
-1. Create a new Pro Tools session, name this session after your project.
+#. Create a new Pro Tools session, name this session after your project.
-1. Create new tracks, one for each character. Name each track after a 
+#. Create new tracks, one for each character. Name each track after a 
    character.
-1. On each track, create a clip group (or edit in some audio) at the time you 
+#. On each track, create a clip group (or edit in some audio) at the time you 
    would like an ADR line to appear in the report. Name the clip after the 
    dialogue you are replacing at that time.
 
 
-## Step 2: Add More Information to Your Spots
+Step 2: Add More Information to Your Spots
+------------------------------------------
 
 Clips, tracks and markers in your session can contain additional information 
 to make your ADR reports more complete and useful. You add this information 
 with *tagging*.
 
-- Every ADR clip must have a unique cue number. After the name of each clip,
+* Every ADR clip must have a unique cue number. After the name of each clip,
   add the letters "$QN=" and then a unique number (any combination of letters 
   or numbers that don't contain a space). You can type these yourself or add 
   them with batch-renaming when you're done spotting.
-- ADR spots should usually have a reason indicated, so you can remember exactly
+* ADR spots should usually have a reason indicated, so you can remember exactly
   why you're replacing a particular line. Do this by adding the the text "{R="
   to your clip names after the prompt and then some short text describing the 
   reason, and then a closing "}". You can type anything, including spaces.
-- If a line is a TV cover line, you can add the text "[TV]" to the end.
+* If a line is a TV cover line, you can add the text "[TV]" to the end.
 
 So for example, some ADR spot's clip name might look like:
 
@@ -35,23 +43,19 @@ So for example, some ADR spot's clip name might look like:
 
 These tags can appear in any order.
 
-- You can add the name of an actor to a character's track, so this information
+* You can add the name of an actor to a character's track, so this information
   will appear on your reports. In the track name, or in the track comments,
   type "{Actor=xxx}" replacing the xxx with the actor's name.
-- Characters need to have a number (perhaps from the cast list) to express how
+* Characters need to have a number (perhaps from the cast list) to express how
   they should be collated. Add "$CN=xxx" with a unique number to each track (or
   the track's comments.)
-- Set the scene for each line with markers. Create a marker at the beginning of 
+* Set the scene for each line with markers. Create a marker at the beginning of 
   a scene and make it's name "{Sc=xxx}", replacing the xxx with the scene 
   number and name.
 
-Many tags are available to express different details of each line, like 
-priority, time budget, picture version and reel, notes etc. charater or the 
-project, find them by running `ptulsconv` with the `--show-available-tags`
-option.
 
-
+Step 3: Export Tracks from Pro Tools as a Text File
-## Step 3: Export Relevant Tracks from Pro Tools as a Text File
+---------------------------------------------------
 
 Export the file as a UTF-8 and be sure to include clips and markers. Export 
 using the Timecode time format.
@@ -59,7 +63,8 @@ using the Timecode time format.
 Do not export crossfades.
 
 
-## Step 4: Run `ptulsconv` on the Text Export
+Step 4: Run `ptulsconv` on the Text Export
+------------------------------------------
 
 In your Terminal, run the following command:
 

docs/source/tagging.rst

@@ -1,15 +1,8 @@
-# How To Use `ptulsconv`
+Tagging
+=======
 
-## Theory of Operation
+Fields in Clip Names
-
+--------------------
-[Avid Pro Tools][avp] exports a tab-delimited text file organized in multiple 
-parts with an uneven syntax that usually can't "drop in" to other tools like 
-Excel or Filemaker. `ptulsconv` will accept a text export from Pro Tools and,
-by default, create a set of PDF reports useful for ADR reporting.
-
-## Tagging 
-
-### Fields in Clip Names
 
 Track names, track comments, and clip names can also contain meta-tags, or 
 "fields," to add additional columns to the CSV output. Thus, if a clip has the 
@@ -19,17 +12,21 @@ name:
 
 The row output for this clip will contain columns for the values:
 
-|...| Clip Name| note | V | FX | DESIGN | ...|
+
-|---|------------|------|---|----|--------|----|
++-----+---------------------+-------------------+---+----+--------+-----+
-|...| Fireworks explosion| Replace for final | 1 | FX | DESIGN | ... |
+| ... | Clip Name           | note              | V | FX | DESIGN | ... |
++=====+=====================+===================+===+====+========+=====+
+| ... | Fireworks explosion | Replace for final | 1 | FX | DESIGN | ... |
++-----+---------------------+-------------------+---+----+--------+-----+
+
 
 These fields can be defined in the clip name in three ways:
 * `$NAME=VALUE` creates a field named `NAME` with a one-word value `VALUE`.
 * `{NAME=VALUE}` creates a field named `NAME` with the value `VALUE`. `VALUE` 
-  in this case may contain spaces or any chartacter up to the closing bracket.
+in this case may contain spaces or any chartacter up to the closing bracket.
 * `[NAME]` creates a field named `NAME` with a value `NAME`. This can be used 
-  to create a boolean-valued field; in the CSV output, clips with the field 
+to create a boolean-valued field; in the CSV output, clips with the field 
-  will have it, and clips without will have the column with an empty value.
+will have it, and clips without will have the column with an empty value.
 
 For example, if two clips are named:
 
@@ -39,13 +36,19 @@ For example, if two clips are named:
 
 The output will contain the range:
 
-|...| PT.Clip.Name| Ch | FUTZ | ADR | ...|
-|---|------------|------|---|----|-----|
-|...| "Squad fifty-one, what is your status?"| Dispatcher | FUTZ | ADR | ... |
-|...| "We are ten-eight at Rampart Hospital."| Gage |  | ADR | ... |
 
 
-### Fields in Track Names and Markers
++-----+-----------------------------------------+------------+------+-----+
+| ... | Clip Name                               | Ch         | FUTZ | ADR |
++=====+=========================================+============+======+=====+
+| ... | "Squad fifty-one, what is your status?" | Dispatcher | FUTZ | ADR |
++-----+-----------------------------------------+------------+------+-----+
+| ... | "We are ten-eight at Rampart Hospital." | Gage       |      | ADR |
++-----+-----------------------------------------+------------+------+-----+
+
+
+Fields in Track Names and Markers
+---------------------------------
 
 Fields set in track names, and in track comments, will be applied to *each* 
 clip on that track. If a track comment contains the text `{Dept=Foley}` for 
@@ -63,7 +66,8 @@ An important note here is that, always, fields set on the clip name have the
 highest precedence. If a field is set in a clip name, the same field set on the 
 track, the value set on the clip will prevail.
 
-### Using `@` to Apply Fields to a Span of Clips
+Using @ to Apply Fields to a Time Range of Clips
+--------------------------------------------------
 
 A clip name beginning with "@" will not be included in the CSV output, but its 
 fields will be applied to clips within its time range on lower tracks.
@@ -71,22 +75,12 @@ fields will be applied to clips within its time range on lower tracks.
 If track 1 has a clip named `@ {Sc=1- The House}`, any clips beginning within 
 that range on lower tracks will have a field `Sc` with that value.
 
-### Using `&` to Combine Clips
+Using & to Combine Clips
+--------------------------
 
 A clip name beginning with `&` will have its parsed clip name appended to the 
 preceding cue, and the fields of following cues will be applied, earlier clips 
 having precedence. The clips need not be touching, and the clips will be 
 combined into a single row of the output. The start time of the first clip will
 become the start time of the row, and the finish time of the last clip will 
-become the finish time of the row.
+become the finish time of the row.
-
-
-## What is `ptulsconv` Useful For?
-
-The main purpose of `ptulsconv` is to read a Pro Tools text export and convert 
-it into PDFs useful for ADR recording.
-
-
-## Is it useful for anything else?
-
-

man/ptulsconv.1

@@ -1,18 +0,0 @@
-.\" Manpage for ptulsconv
-.\" Contact https://github.com/iluvcapra/ptulsconv
-.TH ptulsconv 1 "15 May 2020" "0.8.2" "ptulsconv man page"
-.SH NAME
-.BR "ptulsconv" " \- convert 
-.IR "Avid Pro Tools" " text exports"
-.SH SYNOPSIS
-ptulsconv [OPTIONS] Export.txt
-.SH DESCRIPTION
-Convert a Pro Tools text export into ADR reports.
-.SH OPTIONS
-.IP "-h, --help"
-show a help message and exit.
-.TP
-.RI "--show-available-tags"
-Print a list of tags that are interpreted and exit.
-.SH AUTHOR
-Jamie Hardt (contact at https://github.com/iluvcapra/ptulsconv)