Add MediaThread user documentation using MkDocs

README-DOCS.txt

@@ -0,0 +1,17 @@
+# Mediathread Documentation
+
+The user and developer documentation has been generated using MkDocs.
+
+## Viewing the Documentation
+
+### Option 1: Static HTML (Recommended)
+Open the following file in your web browser:
+`site/index.html`
+
+### Option 2: Live Server
+To browse the documentation with a live server (useful if you are editing it):
+Run `mkdocs serve` in your terminal and visit `http://127.0.0.1:8000`.
+
+## Structure
+The source markdown files are located in the `docs/` directory.
+Configuration is in `mkdocs.yml`.

docs/admin-guide/authentication.md

@@ -0,0 +1,41 @@
+# Authentication Configuration
+
+Mediathread supports multiple authentication backends to suit different institutional needs.
+
+## LTI (Learning Tools Interoperability)
+
+This is the preferred method for integrating with Learning Management Systems (LMS) like Canvas, Blackboard, or Moodle.
+
+### Configuration
+1.  Ensure `lti_auth` is in `INSTALLED_APPS` (it is by default).
+2.  The LTI launch endpoint is usually mapped in `lti_auth/urls.py`.
+3.  You will need to configure the **Consumer Key** and **Shared Secret** in the Mediathread Admin interface (`/admin`).
+    *   Go to **LTI Tool** > **LTI Consumers**.
+    *   Add a new Consumer with the key/secret provided to your LMS administrator.
+
+### Behavior
+When a user launches Mediathread from an LMS:
+*   **Account Creation:** If the user doesn't exist, an account is auto-created based on the LTI data.
+*   **Role Mapping:** LTI roles (Instructor, Learner) are mapped to Mediathread Course roles (Faculty, Student).
+*   **Course Context:** The user is automatically placed into the correct Course context.
+
+## CAS (Central Authentication Service)
+
+For university-wide Single Sign-On (SSO).
+
+### Configuration
+1.  Install `django-cas-ng`.
+2.  Add to `AUTHENTICATION_BACKENDS` in your settings:
+    ```python
+    AUTHENTICATION_BACKENDS = (
+        'django.contrib.auth.backends.ModelBackend',
+        'django_cas_ng.backends.CASBackend',
+    )
+    ```
+3.  Configure `CAS_SERVER_URL` in `local_settings.py`.
+
+## Local Accounts
+
+Mediathread uses `django-registration-redux` for local email/password accounts. This is useful for guest users or testing.
+*   Users can sign up via the registration form (if enabled).
+*   Admins can create accounts manually via `manage.py` or the Admin site.

docs/admin-guide/cli.md

@@ -0,0 +1,24 @@
+# CLI & Management Commands
+
+Mediathread is managed via the standard Django `manage.py` utility.
+
+## Common Commands
+
+Run these commands from the root of the project (or inside the Docker container).
+
+### Database Management
+*   `./manage.py migrate`: Applies database schema changes.
+*   `./manage.py createsuperuser`: Creates an administrative account with full permissions.
+
+### Static Files
+*   `./manage.py collectstatic`: Gathers all static files (CSS, JS, Images) into the `static/` directory for production serving.
+
+### User Management
+*   `./manage.py change_password <username>`: Resets a user's password.
+
+### Testing
+*   `./manage.py test`: Runs the Python unit tests.
+*   `make cypress`: Runs the Cypress end-to-end integration tests (requires Node.js).
+
+## Custom Commands
+(Check `manage.py help` for a full list of available commands, including any custom management commands added by installed apps.)

docs/admin-guide/installation.md

@@ -0,0 +1,49 @@
+# Installation & Deployment
+
+Mediathread is a complex Django application dependent on several services. We recommend using Docker for development and evaluation, and a standard WSGI setup (Apache/Nginx) for production.
+
+## Requirements
+*   **Python:** >= 3.8
+*   **Database:** PostgreSQL (Recommended)
+*   **JavaScript:** Node.js & NPM (for building the frontend)
+*   **Video Player:** Flowplayer installation (optional, for legacy support)
+*   **External Services:** Flickr API Key (optional)
+
+## Docker (Development)
+
+The easiest way to spin up Mediathread is using Docker Compose.
+
+1.  **Clone the repository:**
+    ```bash
+    git clone https://github.com/ccnmtl/mediathread.git
+    cd mediathread
+    ```
+
+2.  **Build the images:**
+    ```bash
+    make build
+    ```
+
+3.  **Initialize the database:**
+    ```bash
+    docker-compose run web migrate
+    docker-compose run web manage createsuperuser
+    ```
+
+4.  **Run the application:**
+    ```bash
+    docker-compose up
+    ```
+    The site will be available at `http://localhost:8000`.
+
+## Production Deployment
+
+For production, we utilize standard Django deployment practices.
+
+1.  **Virtual Environment:** Create a virtualenv and install dependencies from `requirements.txt`.
+2.  **Static Files:** Run `./manage.py collectstatic` to gather CSS/JS assets.
+3.  **WSGI Server:** Use Gunicorn or Apache with `mod_wsgi`. Sample Apache configs are in `apache/`.
+4.  **Settings:** Create a `deploy_specific/settings.py` to override `settings_shared.py`.
+    *   Set `DEBUG = False`
+    *   Configure `DATABASES`
+    *   Set `ALLOWED_HOSTS`

docs/contributor-guide/api.md

@@ -0,0 +1,18 @@
+# API Reference
+
+Mediathread provides several API endpoints for interacting with data programmatically.
+
+## Authentication
+Most API endpoints require session authentication (cookie-based) or LTI context.
+
+## Core Endpoints
+
+### Assets
+*   `GET /api/v2/assets/`: List available assets.
+*   `POST /save/`: Endpoint for the Browser Extension to create new assets.
+
+### Annotations
+*   `GET /api/v2/annotations/`: Retrieve annotations for a specific asset.
+*   `POST /api/v2/annotations/`: Create a new annotation.
+
+*(Note: The API is currently primarily for internal use by the React frontend and is subject to change.)*

docs/contributor-guide/architecture.md

@@ -0,0 +1,33 @@
+# Architecture Overview
+
+Mediathread is a hybrid application combining a robust Django backend with a modern React frontend.
+
+## Backend (Django)
+
+The backend is structured into several reusable Django apps located in `mediathread/`.
+
+*   **`mediathread.main`**: Core functionality, home views, and shared utilities.
+*   **`mediathread.projects`**: Manages "Projects" (collections of assets).
+*   **`mediathread.assetmgr`**: Handles asset upload, storage, and metadata.
+*   **`mediathread.taxonomy`**: Manages tagging vocabularies.
+*   **`lti_auth`**: Handles LTI authentication logic.
+
+### API Layer
+Mediathread exposes data via two API frameworks:
+1.  **Django Tastypie:** Used for older legacy APIs (Courses, Taxonomy).
+2.  **Django REST Framework / Custom JSON Views:** Used for newer features and the React frontend.
+
+## Frontend (React & Webpack)
+
+The interactive parts of the application (specifically the Asset Analysis and Annotation interfaces) are built with React.
+
+*   **Entry Points:** Defined in `webpack.config.js`.
+*   **State Management:** React components manage local state for annotations and selections.
+*   **Build System:** Webpack compiles ES6+ JavaScript and JSX into bundles served by Django.
+
+## Database Schema
+The application relies on **PostgreSQL**. Key models include:
+*   `Course`: The central organizational unit.
+*   `Asset`: Represents a media file (video/image).
+*   `AssetSelection`: A specific time-range or crop of an Asset.
+*   `Composition`: A user-created document embedding AssetSelections.

docs/contributor-guide/development.md

@@ -0,0 +1,30 @@
+# Development Setup
+
+We welcome contributions! Follow these steps to set up your environment.
+
+## Prerequisites
+*   Docker & Docker Compose (Recommended)
+*   Node.js & NPM (for frontend changes)
+
+## Getting Started
+
+1.  **Fork & Clone:** Fork the repo on GitHub and clone it locally.
+2.  **Build Environment:**
+    ```bash
+    make build
+    ```
+3.  **Run Tests:**
+    Always run tests before submitting a PR.
+    *   **Unit Tests:** `docker-compose run web manage test`
+    *   **Integration Tests:** `make cypress`
+
+## Code Style
+*   **Python:** We follow PEP 8. Usage of linters (flake8) is encouraged.
+*   **JavaScript:** We use ESLint. Run `npm run lint` to check your code.
+
+## Making Changes
+1.  Create a feature branch (`git checkout -b feature/my-new-feature`).
+2.  Make your changes.
+3.  Write tests covering your changes.
+4.  Run the full test suite.
+5.  Push to your fork and submit a Pull Request.

docs/index.md

@@ -0,0 +1,17 @@
+# Welcome to Mediathread
+
+**Mediathread** is a collaborative multimedia analysis platform developed by the Columbia Center for New Media Teaching and Learning (CCNMTL). It allows instructors and students to upload, organize, and annotate video and image assets within a shared course environment.
+
+## Key Features
+
+*   **Multimedia Annotation:** Analyze videos and images with precise time-based or spatial selections.
+*   **Course-Centric:** Organize content by courses with distinct roles for Instructors and Students.
+*   **LTI Integration:** Seamlessly integrates with Learning Management Systems (LMS) like Canvas, Blackboard, and Moodle.
+*   **Browser Extension:** Import metadata and assets from external libraries (like Flickr or YouTube) directly into your course.
+*   **Collections:** Organize assets into reusable Collections and Sequences.
+
+## Documentation Structure
+
+*   **[User Guide](user-guide/intro.md):** For students and instructors learning how to use the platform.
+*   **[Administrator Guide](admin-guide/installation.md):** For system admins deploying and configuring Mediathread.
+*   **[Contributor Guide](contributor-guide/architecture.md):** For developers who want to contribute to the open-source codebase.

docs/user-guide/courses.md

@@ -0,0 +1,33 @@
+# Courses & Assignments
+
+Mediathread organizes all activity within **Courses**. A Course contains members (Instructors, Students), Assets, and Assignments.
+
+## For Instructors
+
+### Creating a Course
+Courses are typically created by administrators or via LTI integration. Once a course exists, you can manage it:
+1.  Navigate to the **Course Settings** tab.
+2.  Manage the **Roster** to add or remove students manually (if not using LTI).
+
+### Assignments
+Instructors can create several types of assignments:
+*   **Composition Assignment:** Students write a multimedia essay embedding selections.
+*   **Selection Assignment:** Students must identify and annotate specific parts of an asset.
+*   **Sequence Assignment:** Students order assets or selections into a narrative sequence.
+
+To create an assignment:
+1.  Go to the **Assignments** tab.
+2.  Click **Create Assignment**.
+3.  Choose the type and set the due date and instructions.
+
+## For Students
+
+### Your Dashboard
+When you log in, you will see a list of your active Courses. Inside a course, your **Dashboard** shows:
+*   **Upcoming Assignments:** Tasks you need to complete.
+*   **Recent Activity:** New assets or discussions in the course.
+
+### Submitting Work
+1.  Click on an Assignment to open it.
+2.  Follow the instructions to create your Composition or Selections.
+3.  Click **Submit** when finished. Once submitted, you may not be able to edit your work depending on the assignment settings.

docs/user-guide/extensions.md

@@ -0,0 +1,28 @@
+# Browser Extensions & Integration
+
+Mediathread offers tools to integrate with your web browsing experience, allowing you to bring external content into your course environment easily.
+
+## The "Save to Mediathread" Bookmarklet
+
+The primary tool for external content is the **Mediathread Bookmarklet** (often referred to as the browser extension).
+
+### Installation
+1.  Log in to Mediathread.
+2.  Look for the **"Tools"** or **"Bookmarklet"** link in the footer or your profile menu.
+3.  Drag the **"Save to Mediathread"** button to your browser's Bookmarks Bar.
+
+### Usage
+1.  Browse to a supported site (e.g., Flickr, YouTube, or a library archive).
+2.  When you see an image or video you want to analyze, click the **"Save to Mediathread"** bookmark in your bar.
+3.  A popup will appear, analyzing the page for compatible metadata (Schema.org, etc.).
+4.  Select the Course you want to save the asset to.
+5.  Click **Save**. The asset is now available in your Mediathread Collection.
+
+## Metadata Standards (Schema.org)
+Mediathread relies on structured metadata to understand external pages. It specifically looks for **Schema.org** markup (using `itemscope`, `itemtype`, and `itemprop`).
+
+*   **Why is this important?** It allows Mediathread to automatically pull in the Title, Author, License, and Source URL of the media.
+*   **Extensions:** While we use the term "Extension" to describe this capability, it is technically a Javascript bookmarklet that acts as a bridge between the open web and your private course.
+
+!!! note "MCP"
+    You may have heard of other integration protocols. Mediathread focuses on **LTI** for LMS integration and **Schema.org/Bookmarklets** for content integration. It does not currently utilize the "Model Context Protocol" (MCP).

docs/user-guide/intro.md

@@ -0,0 +1,21 @@
+# User Guide Introduction
+
+Mediathread is designed to help you build arguments and analysis around multimedia objects. Whether you are an instructor creating assignments or a student completing them, the workflow centers on **Assets** and **Selections**.
+
+## Core Concepts
+
+### Assets
+An **Asset** is any media item (Video, Audio, Image) brought into Mediathread. Assets can be:
+*   Uploaded directly to Mediathread.
+*   Imported from external sites via the [Browser Extension](extensions.md).
+*   Shared across a Course.
+
+### Selections
+A **Selection** is a specific piece of an Asset.
+*   **For Video/Audio:** A time range (e.g., "0:10 to 0:45").
+*   **For Images:** A cropped rectangular region.
+
+You "annotate" by creating a Selection and adding text to it. These Selections can then be embedded into Compositions or Discussions.
+
+### Compositions
+A **Composition** is a multimedia essay. Instead of just writing text, you embed your Selections directly into the document. This allows readers to click a Selection and immediately see/hear the evidence you are citing.

docs/user-guide/multimedia.md

@@ -0,0 +1,27 @@
+# Multimedia & Annotations
+
+The heart of Mediathread is the analysis of media.
+
+## Adding Assets
+You can bring media into your course in two ways:
+1.  **Upload:** Click the **"Upload"** button in the header to upload video, audio, or image files from your computer.
+2.  **Import:** Use the **Browser Extension** to grab media from the web (see [Browser Extensions](extensions.md)).
+
+## The "Asset View"
+When you click on a video or image, you enter the **Asset View**.
+
+### Annotating Video
+1.  Play the video.
+2.  Click **"Start Selection"** (or press `i`) to mark the beginning of a clip.
+3.  Click **"End Selection"** (or press `o`) to mark the end.
+4.  Click **"Save"**.
+5.  Add a Title and Description (your annotation) to the clip.
+
+### Annotating Images
+1.  Click and drag on the image to draw a box.
+2.  Resize the box to highlight the specific area of interest.
+3.  Click **"Save"** and add your annotation text.
+
+## The "Collection" and "Workspace"
+*   **Collection:** A personal library of your saved Selections. You can filter these by tags or search terms.
+*   **Workspace:** The area where you build Compositions. You drag and drop your saved Selections from the Collection into the Workspace to build your analysis.

mkdocs.yml

@@ -0,0 +1,32 @@
+site_name: Mediathread Documentation
+site_description: Comprehensive documentation for Mediathread, a multimedia annotation platform.
+site_url: https://ccnmtl.github.io/mediathread/
+
+theme:
+  name: material
+  features:
+    - navigation.sections
+    - search.suggest
+    - search.highlight
+
+nav:
+  - Home: index.md
+  - User Guide:
+    - Introduction: user-guide/intro.md
+    - Courses & Assignments: user-guide/courses.md
+    - Multimedia & Annotations: user-guide/multimedia.md
+    - Browser Extensions: user-guide/extensions.md
+  - Administrator Guide:
+    - Installation & Deployment: admin-guide/installation.md
+    - Authentication (LTI/CAS): admin-guide/authentication.md
+    - CLI & Management: admin-guide/cli.md
+  - Contributor Guide:
+    - Architecture Overview: contributor-guide/architecture.md
+    - Development Setup: contributor-guide/development.md
+    - API Reference: contributor-guide/api.md
+
+markdown_extensions:
+  - admonition
+  - codehilite
+  - pymdownx.details
+  - pymdownx.superfences