danvics/ytdl-sub
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

[DOCS] Clarify debugging, support, reporting (#1305)

Browse source 
Reconcile the various debugging hints throughout the documentation and integrate into a
central debugging page. Includes clarification of the roles of ytdl-sub, yt-dlp, and
external services. Also adds cross references to the relevant bits across the docs.
This commit is contained in:
Ross Patterson 2025-08-27 09:10:01 -07:00 committed by GitHub
parent abd75f8005
commit 895e6ea972
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 129 additions and 62 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

17
docs/source/config_reference/scripting/scripting_functions.rst
View file

@ -538,27 +538,26 @@ print
:spec: ``print(message: AnyArgument, passthrough: ReturnableArgument, level: Optional[Integer]) -> ReturnableArgument``
:description:
Print the ``message`` and return ``passthrough``.
Optionally can pass level, where < 0 is debug, 0 is info, 1 is warning, > 1 is error.
Defaults to info.
Log the ``message`` and return ``passthrough``. Optionally can pass level,
where < 0 is debug, 0 is info, 1 is warning, > 1 is error. (default ``0``)
print_if_false
~~~~~~~~~~~~~~
:spec: ``print_if_false(message: AnyArgument, passthrough: ReturnableArgument, level: Optional[Integer]) -> ReturnableArgument``
:description:
Print the ``message`` if ``passthrough`` evaluates to ``false``. Return ``passthrough``.
Optionally can pass level, where < 0 is debug, 0 is info, 1 is warning, > 1 is error.
Defaults to info.
Log the ``message`` if ``passthrough`` evaluates to ``false``. Return
``passthrough``. Optionally can pass level, where < 0 is debug, 0 is info, 1
is warning, > 1 is error. (default ``0``)
print_if_true
~~~~~~~~~~~~~
:spec: ``print_if_true(message: AnyArgument, passthrough: ReturnableArgument, level: Optional[Integer]) -> ReturnableArgument``
:description:
Print the ``message`` if ``passthrough`` evaluates to ``true``. Return ``passthrough``.
Optionally can pass level, where < 0 is debug, 0 is info, 1 is warning, > 1 is error.
Defaults to info.
Log the ``message`` if ``passthrough`` evaluates to ``true``. Return
``passthrough``. Optionally can pass level, where < 0 is debug, 0 is info, 1
is warning, > 1 is error. (default ``0``)
----------------------------------------------------------------------------------------------------

80
docs/source/debugging.rst Normal file
View file

@ -0,0 +1,80 @@
Debugging
=========
Run with the ``--log-level verbose`` CLI option to see more information in the output,
such as all ``yt-dlp`` logs. Run with ``--log-level debug`` to show all log messages,
often too much information for normal operation but useful when investigating a specific
problem.
:ref:`ytdl-sub builds on yt-dlp <introduction:motivation>`, which is in itself a complex
tool. It performs an intricate and fragile task, web scraping, which in turn :ref:`is
subject to the whims of external services <guides/getting_started/index:minimize the
work to only what's necessary>` outside its control. Finally, because :ref:`ytdl-sub is
a lower-level tool <guides/getting_started/index:prerequisite knowledge>`, many users,
if not most, will have problems getting their configuration working and it can be
difficult to determine when the root cause is their configuration, just a limit imposed
by the services, or, least likely, a bug in one of the tools involved.
To expedite resolution and conserve the limited resources of both yourself and
volunteers, do as much investigation yourself as you can:
#. Start by assuming the issue is your configuration:
Review :doc:`the guides <./guides/index>` to confirm your understanding. Increase
output using the ``--log-level`` CLI option and read the output carefully for hints
and clues. Use those clues to `search the docs`_. Read :doc:`the reference docs
<./config_reference/index>` of the involved ``ytdl-sub`` components.
#. Try to determine if the issue is happening in ``yt-dlp`` or ``ytdl-sub``:
The user's configuration tells ``ytdl-sub`` how to run ``yt-dlp``. ``yt-dlp`` handles
all the web scraping and downloading. ``ytdl-sub`` then assembles the files and metadata
produced by ``yt-dlp`` and places them in your library.
If the issue is happening while scraping or downloading from the external service,
then it's happening in the running of ``yt-dlp``. Look for output showing failed
downloads, ``403`` errors, or signs of throttles. That doesn't mean it's a bug in
``yt-dlp``, it could be in how your configuration tells ``ytdl-sub`` to run
``yt-dlp`` or limits imposed by the service that are constantly changing, but you may
be able to find answers from other ``yt-dlp`` users running into similar issues.
See `the yt-dlp known issues`_ and `search their issues`_ for clues and hints. Read
the comments for more understanding, workarounds, and maybe even fixes. If you still
don't understand the cause after reading everything you can find there, try to find
help in `the yt-dlp Discord`_.
#. If the issue is happening in ``ytdl-sub``, reach out for help:
Once you've done everything you can to get your configuration working and you've
determined that the issue isn't happening in ``yt-dlp``, look for answers in
``ytdl-sub``:
#. Cut your configuration and subscriptions down to the minimum that reproduces the
issue.
#. Run with the ``--log-level debug`` CLI option and copy the full output.
#. `Search the ytdl-sub issues`_ using clues and hints from the output.
#. `Open a support post in Discord`_ with those details and all other relevant
details.
#. If someone from the Discord discussion directs you to, then `open a new issue`_
with those same details.
.. _`the yt-dlp known issues`:
https://github.com/yt-dlp/yt-dlp/wiki/FAQ#known-issues
.. _`search their issues`:
https://github.com/yt-dlp/yt-dlp/issues
.. _`the yt-dlp Discord`:
https://discord.gg/H5MNcFW63r
.. _`search the docs`:
https://ytdl-sub.readthedocs.io/en/latest/search.html
.. _`search the ytdl-sub issues`:
https://github.com/jmbannon/ytdl-sub/issues
.. _`open a support post in Discord`:
https://discord.com/channels/994270357957648404/1084886228266127460
.. _`open a new issue`:
https://github.com/jmbannon/ytdl-sub/issues/new

59
docs/source/faq/index.rst
View file

@ -25,26 +25,6 @@ by media players. This can be overwritten as you see fit by redefining it:
overrides:
episode_title: "{title}" # Only sets the video title
...get support or reach out to contribute?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you need support, you can:
* :ytdl-sub-gh:`Open an issue on GitHub <issues/new>`
* `Join our Discord <https://discord.gg/v8j9RAHb4k>`_
If you would like to contribute, we're happy to accept any help, even non-coders! To
find out how you can help this project, you can:
* `Join our Discord <https://discord.gg/v8j9RAHb4k>`_ and leave a comment in
#development with where you think you can assist or what skills you would like to
contribute.
* If you just want to fix one thing, you're welcome to :ytdl-sub-gh:`submit a pull
request <compare>` with information on what issue you're resolving and it will be
reviewed as soon as possible.
...download age-restricted YouTube videos?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -218,24 +198,41 @@ use `the same CLI options as re-downloading a file`_
.. _`the same CLI options as re-downloading a file`:
`...force ytdl-sub to re-download a file`_
...get support?
~~~~~~~~~~~~~~~
See :doc:`the debugging documentation <../debugging>`.
...reach out to contribute?
~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you would like to contribute, we're happy to accept any help, including from
non-coders! To find out how you can help this project, you can:
- `Join our Discord <https://discord.gg/v8j9RAHb4k>`_ and leave a comment in
#development with where you think you can assist or what skills you would like to
contribute.
- If you just want to fix one thing, you're welcome to :ytdl-sub-gh:`submit a pull
request <compare>` with information on what issue you're resolving and it will be
reviewed as soon as possible.
There is a bug where...
-----------------------
..ytdl-sub is not downloading
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
...ytdl-sub is not downloading
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Run with ``--log-level verbose`` to see all yt-dlp logs, to rule out whether it is a
yt-dlp or ytdl-sub issue.
...ytdl-sub is downloading at 360p or other lower quality
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Any logs showing failed downloads, 403 errors, signs of throttles, etc, are a yt-dlp
issue. A good strategy is to see if your same issue has been reported in `yt-dlp's
GitHub issues <https://github.com/yt-dlp/yt-dlp/issues>`_, and search to see if there is
a comment including a fix or workaround.
...ytdl-sub downloads 2-4 videos and then fails
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If it looks like a ytdl-sub issue, run with ``--log-level debug`` and make a `GitHub
issue in ytdl-sub <https://github.com/jmbannon/ytdl-sub/issues>`_ containing these logs
and other relevant info.
These are often just limits imposed by the external services that are not bugs. There
may be little that can be done about them, but see :ref:`the '_throttle_protection'
preset <prebuilt_presets/helpers:_throttle_protection>` for more information.
...date_range is not downloading older videos after I changed the range
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

17
docs/source/guides/development/index.rst
View file

@ -72,21 +72,12 @@ but is highly recommended.
TODO: screenshots of configuration
Debugging
---------
Debug Logs
^^^^^^^^^^
Run with ``--log-level debug`` to show all debug logs when running ytdl-sub.
Reproducing a Failing Subscription
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
----------------------------------
Subscriptions will dump their entire *compiled* yaml at the beginning of exeuction when
using ``--log-level debug``. This can be copy-pasted into the file
``resources/file_fixtures/repro.yaml``.
Subscriptions will dump their entire *compiled* yaml at the beginning of exeuction
:doc:`when using '--log-level debug' <../../debugging>`. This can be copy-pasted into
the file ``resources/file_fixtures/repro.yaml``.
Running the test ``e2e.test_debug_repro.TestReproduce.test_debug_log_repro`` will fully
reproduce that subscription in order to debug it.

1
docs/source/index.rst
View file

@ -10,5 +10,6 @@ ytdl-sub User Guide
prebuilt_presets/index
usage
config_reference/index
debugging
faq/index
deprecation_notices

17
src/ytdl_sub/script/functions/print_functions.py
View file

@ -34,9 +34,8 @@ class PrintFunctions:
) -> ReturnableArgument:
"""
:description:
Print the ``message`` and return ``passthrough``.
Optionally can pass level, where < 0 is debug, 0 is info, 1 is warning, > 1 is error.
Defaults to info.
Log the ``message`` and return ``passthrough``. Optionally can pass level,
where < 0 is debug, 0 is info, 1 is warning, > 1 is error. (default ``0``)
"""
_log(message=message, level=level)
return passthrough
@ -47,9 +46,9 @@ class PrintFunctions:
) -> ReturnableArgument:
"""
:description:
Print the ``message`` if ``passthrough`` evaluates to ``true``. Return ``passthrough``.
Optionally can pass level, where < 0 is debug, 0 is info, 1 is warning, > 1 is error.
Defaults to info.
Log the ``message`` if ``passthrough`` evaluates to ``true``. Return
``passthrough``. Optionally can pass level, where < 0 is debug, 0 is info, 1
is warning, > 1 is error. (default ``0``)
"""
if passthrough.value:
_log(message=message, level=level)
@ -61,9 +60,9 @@ class PrintFunctions:
) -> ReturnableArgument:
"""
:description:
Print the ``message`` if ``passthrough`` evaluates to ``false``. Return ``passthrough``.
Optionally can pass level, where < 0 is debug, 0 is info, 1 is warning, > 1 is error.
Defaults to info.
Log the ``message`` if ``passthrough`` evaluates to ``false``. Return
``passthrough``. Optionally can pass level, where < 0 is debug, 0 is info, 1
is warning, > 1 is error. (default ``0``)
"""
if not passthrough.value:
_log(message=message, level=level)