From 895e6ea972e17cdbb7aa99c0c37ac8da35d30d56 Mon Sep 17 00:00:00 2001 From: Ross Patterson Date: Wed, 27 Aug 2025 09:10:01 -0700 Subject: [PATCH] [DOCS] Clarify debugging, support, reporting (#1305) 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. --- .../scripting/scripting_functions.rst | 17 ++-- docs/source/debugging.rst | 80 +++++++++++++++++++ docs/source/faq/index.rst | 59 +++++++------- docs/source/guides/development/index.rst | 17 +--- docs/source/index.rst | 1 + .../script/functions/print_functions.py | 17 ++-- 6 files changed, 129 insertions(+), 62 deletions(-) create mode 100644 docs/source/debugging.rst diff --git a/docs/source/config_reference/scripting/scripting_functions.rst b/docs/source/config_reference/scripting/scripting_functions.rst index 77f945ed..d6064e0f 100644 --- a/docs/source/config_reference/scripting/scripting_functions.rst +++ b/docs/source/config_reference/scripting/scripting_functions.rst @@ -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``) ---------------------------------------------------------------------------------------------------- diff --git a/docs/source/debugging.rst b/docs/source/debugging.rst new file mode 100644 index 00000000..ffc271fd --- /dev/null +++ b/docs/source/debugging.rst @@ -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 `, 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 ` outside its control. Finally, because :ref:`ytdl-sub is +a lower-level tool `, 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 diff --git a/docs/source/faq/index.rst b/docs/source/faq/index.rst index 0a2105c0..63a96657 100644 --- a/docs/source/faq/index.rst +++ b/docs/source/faq/index.rst @@ -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 ` - -* `Join our Discord `_ - -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 `_ 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 ` 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 `_ 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 ` 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 `_, 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 `_ 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 ` for more information. ...date_range is not downloading older videos after I changed the range ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/source/guides/development/index.rst b/docs/source/guides/development/index.rst index 7a36843f..4dfdb3c9 100644 --- a/docs/source/guides/development/index.rst +++ b/docs/source/guides/development/index.rst @@ -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. diff --git a/docs/source/index.rst b/docs/source/index.rst index 99727301..f25c08cd 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -10,5 +10,6 @@ ytdl-sub User Guide prebuilt_presets/index usage config_reference/index + debugging faq/index deprecation_notices diff --git a/src/ytdl_sub/script/functions/print_functions.py b/src/ytdl_sub/script/functions/print_functions.py index 79113f1c..47084085 100644 --- a/src/ytdl_sub/script/functions/print_functions.py +++ b/src/ytdl_sub/script/functions/print_functions.py @@ -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)