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).
* docs(docker): Clarify where the configuration is
The docs move from installation with Docker straight to modifying the configuration
without detailing where those files are.
* docs(start): Defining comments is discracting
This one is squarely me with my editor's red pen, do what you will. I whole heartedly
agree with this statement about comments and the intention (I assume) to encourage new
users to comment their configurations early and often. I just think this isn't the right
place for it and makes this document less focused and effective.
* docs(start): Less technical YAML key description
* docs(intro): Update and clarify goals/motivation
To help calibrate our collaboration, I went uninhibited with these changes including:
- assumptions about history I don't actually know:
"this project was one of the early entrants"
- description of the yt-dlp/ytdl-sub division of labor I'm not actually certain about
- max opinion, both about this project and the domain in general
- max cheeky/fun writing tone, with the intention of being personable
- max editor's red pen, cut mercilessly
IOW, review carefully and reject early and often to help me submit future changes that
require less review and revision. To that end, give me more rather than less feedback on
this change in particular.
I include an endorsement of Pinchflat because [they do the same for
ytdl-sub](https://github.com/kieraneglin/pinchflat?tab=readme-ov-file#what-it-does). It
would be my next choice if ytdl-sub couldn't meet my needs or vanquished me. More
than that link, in other Reddit comments and the like, the Pinchflat author clearly
expresses preference for ytdl-sub as their own "next option".
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
