anti-pattern-sphinx-video-downloader¶
We want to be able to have videos in documentation. However, this project should be considered an anti-pattern since it is discouraged to host large files directly inside your Sphinx build outputs. Most hosted solutions for Sphinx projects do not support large video files or are likely to break such support if it becomes problematic.
An anti-pattern in software engineering, project management, and business processes is a common response to a recurring problem that is usually ineffective and risks being highly counterproductive.[1][2] The term, coined in 1995 by computer programmer Andrew Koenig, was inspired by the book Design Patterns (which highlights a number of design patterns in software development that its authors considered to be highly reliable and effective) and first published in his article in the Journal of Object-Oriented Programming.[3] A further paper in 1996 presented by Michael Ackroyd at the Object World West Conference also documented anti-patterns.
https://en.wikipedia.org/wiki/Anti-pattern
Quick brainstorm¶
Here are the disadvantages of many different methods:
Youtube embeds: Commercials + tracking
Peertube embeds: Either run your own instance or use an instance that’s likely unrelated to your interests
Embeds in general: Do not play nicely with CSP, however Youtube might be universally allowed for hosted RTD
Embeds in general: Video takedowns often go un-noticed. That’s why embedded Youtube videos are often broken. Difficult to verify at documentation build time.
Git: Huge binary files in Git aren’t nice
Git LFS: Needs to be configured and added
Git LFS or dynamic downloads: Adds to build time
Git LFS: Do we even want to version a video file?
Dynamic downloads: Nice but we still need a source video available somewhere at build time
Here are some advantages:
Embeds: Multiple bitrates, once it has been created it should Just Work
Downloaded videos can break a build if they do not exist at build time.
Downloaded videos displayed with
<video>
are possible for users to save on their own device.
Usage¶
You need two documentation projects:
Project 1: Your main project, it has a <video> embed pointing to where Project 2 is deployed
Project 2: Use this template, add videos and reference them from whereever this project is built and hosted
Read the Docs setup¶
This is a single-version project meaning that we don’t create heavy archives with previous versions.
No PR builds for Project 2 please
Disable PDF and EPUB builds