* docs(docker): Recommended image DEFAULT_WORKSPACE
* fix(docker): Add default crontab download command
Clarify the `/config/ytdl-sub-configs/cron` script with explanatory comments and a
default `--dry-run` command. Also change the wrapper script to echo commands for easier
debugging. To update an existing script, move the old script aside, restart the
container to regenerate it, and edit the new script.
Also clarify the Automating page in the Getting Started guide docs.
* fix(docker): Unintentional unattended dry runs
[PR feedback](https://github.com/jmbannon/ytdl-sub/pull/1321#discussion_r2315215600)
prompted me to reconsider having a default command at all. We should assume,
unfortunately, that many new users will just skim the docs enough to enable the image's
cron integration but not actually incrementally test their configuration. In those
cases, they'd end up sending dry-run non-download requests for all their subscriptions
every 6 hours for no good reason. There's just no way to provide a default command that
isn't also providing a footgun.
* docs(docker): More open cron schedule generator
From [PR
feedback](https://github.com/jmbannon/ytdl-sub/pull/1321#discussion_r2320521024), this
seems like less of an ad than the previous and the source for the page is itself open source.
* docs(docker): Document image environment footgun
From [PR
feedback](https://github.com/jmbannon/ytdl-sub/pull/1321#discussion_r2320515419).
* docs(automate): Avoid external link 404 responses
* docs(automate): False simultaneous run warning
* docs(automate): Clarify Docker daemon restarts
* docs(automate): Revert run start non-recommended
* docs(automate): Remove footgun manual run command
Addressing this underlying issue requires more thought and should be a separate PR.
* docs(automate): Restore env var footgun in example
* docs(presets): Stale copied prebuilt comment
* docs(start): How to configure subscriptions
Revise the subscriptions file Getting Started tutorial from the perspective of a new
user. The idea is that the ref docs describe a component as the code sees it, whereas
the how-to/tutorial/getting-started docs provide a narrative description of the
component from the external perspective of a typical new user.
* docs(start): Document subscription override mode
It's debatable whether this belongs here. Having moved onto my own custom presets, the
only use cases for override mode in my subscriptions file are for those series that also
have TVDB metadata. Those ytdl-sub downloads I integrate into my Sonarr library need
per-subscription overrides such as:
- Sonarr manages years 2020-2023 for one series and ytdl-sub fills in
from there, so set a `sonarr_series_after: "20240101"` override
- each series needs a directory named per Sonarr's configuration with the TVDB ID, the subscription key,
but also a series name prefix without the TVDB ID for each episode file, so set a
`sonarr_series_prefix: "Foo Series (2020)"` override
So are there other use cases for override mode that are more common and less niche than
mine?
* docs(docker): Revert example bind mount volumes
Per [PR feedback](https://github.com/jmbannon/ytdl-sub/pull/1310#discussion_r2306067263).
I've been running into variations in style in the docs I've edited so far. I've been
including changes for consistency in with other commits but in many cases that makes one
part of one doc more consistent with the rest but less consistent with itself. It seems
like a bit of cleanup may be in order.
This change applies the following conventions:
- Section heading heirarchy:
#. ``=`` with overline for document title, IOW first heading
#. ``-``
#. ``~``
#. ``"``
- Two newlines before ``-`` sections for readability
- A newline between every section of any level and the first line of text
- Wrap paragraph lines at 88 characters to match Python's Black
I've only applied these changes to those ``*.rst`` files that aren't generated.
In the future, I might suggest another bulk change to match [the Sphinx conventions for
section
headings](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections).
- Update Ubuntu-based images to use Python 3.12
- Move hidden files from GUI image's main dir
- Update github workflows to use python 3.12
- Update fixtures
- Minor doc fixes
Drastically simplifies setting up cron within ytdl-sub. Below is the documentation which is available in readthedocs, and a section on how to migrate from the old way to this.
## New Cron Documentation
Cron is preconfigured in every ytdl-sub docker container. Enable by adding the following ENV variables to your docker setup.
```
services:
ytdl-sub:
environment:
- CRON_SCHEDULE="0 */6 * * *"
- CRON_RUN_ON_START=false
```
- CRON_SCHEDULE follows the standard [cron scheduling syntax](https://crontab.guru/#0_*/6_*_*_*). The above value will run the script once every 6 hours.
- CRON_RUN_ON_START toggles whether to run your cron script on container start.
The cron script will reside in the main directory with the file name `cron`. Cron logs should show when viewing the Docker logs.
## Migrating Existing Cron Setup
Containers' cron files will remain intact until you add the `CRON_SCHEDULE` variable. Once you add that with your preferred schedule, it will write that value to /config/crontabs/abc and create a new file `cron` within your working directory. Simply copy everything from your existing `run_cron` script into `cron`.
If you have the ENV variable `DOCKER_MODS` in your docker-compose, remove it. It is now included by default. Not removing this will prevent cron logs from showing in your docker container logs.
Readthedocs for ytdl-sub is getting a massive overhaul to both look and read like a modernized app. It is still very-much work-in-progress, stay tuned for more!
Huge thanks to @Svagtlys (aka Momo) for driving this
