[DOCS] Add warning for auto-generated docs (#1285)

docs/source/config_reference/plugins.rst

@@ -1,3 +1,10 @@
+..
+  WARNING: This RST file is generated from docstrings in:
+    The respective plugin files under src/ytdl_sub/plugins/
+  In order to make a change to this file, edit the respective docstring
+  and run `make docs`. This will automatically sync the Python RST-based
+  docstrings into this file. If the docstrings and RST file are out of sync,
+  it will fail TestDocGen tests in GitHub CI.
 
 Plugins
 =======

docs/source/config_reference/scripting/entry_variables.rst

@@ -1,3 +1,10 @@
+..
+  WARNING: This RST file is generated from docstrings in:
+    src/ytdl_sub/entries/script/variable_definitions.py
+  In order to make a change to this file, edit the respective docstring
+  and run `make docs`. This will automatically sync the Python RST-based
+  docstrings into this file. If the docstrings and RST file are out of sync,
+  it will fail TestDocGen tests in GitHub CI.
 
 Entry Variables
 ===============

docs/source/config_reference/scripting/scripting_functions.rst

@@ -1,3 +1,10 @@
+..
+  WARNING: This RST file is generated from docstrings in:
+    The respective function files under src/ytdl_sub/script/functions/
+  In order to make a change to this file, edit the respective docstring
+  and run `make docs`. This will automatically sync the Python RST-based
+  docstrings into this file. If the docstrings and RST file are out of sync,
+  it will fail TestDocGen tests in GitHub CI.
 
 Scripting Functions
 ===================

docs/source/config_reference/scripting/static_variables.rst

@@ -1,3 +1,10 @@
+..
+  WARNING: This RST file is generated from docstrings in:
+    src/ytdl_sub/entries/variables/override_variables.py
+  In order to make a change to this file, edit the respective docstring
+  and run `make docs`. This will automatically sync the Python RST-based
+  docstrings into this file. If the docstrings and RST file are out of sync,
+  it will fail TestDocGen tests in GitHub CI.
 
 Static Variables
 ================

tools/docgen/docgen.py

@@ -12,6 +12,21 @@ class DocGen:
 
     LOCATION: Path
 
+    # human-readable location of where to edit the underlying docstrings
+    DOCSTRING_LOCATION: str
+
+    @classmethod
+    def _generate_warning(cls) -> str:
+        return (
+            "..\n"
+            "  WARNING: This RST file is generated from docstrings in:\n"
+            f"    {cls.DOCSTRING_LOCATION}\n"
+            "  In order to make a change to this file, edit the respective docstring\n"
+            "  and run `make docs`. This will automatically sync the Python RST-based\n"
+            "  docstrings into this file. If the docstrings and RST file are out of sync,\n"
+            "  it will fail TestDocGen tests in GitHub CI.\n"
+        )
+
     @classmethod
     @abstractmethod
     def generate(cls) -> str:
@@ -25,7 +40,7 @@ class DocGen:
         Maybe writes the docs to their file if the global is set to True, and returns
         the generated docs
         """
-        contents = cls.generate()
+        contents = cls._generate_warning() + cls.generate()
         if REGENERATE_DOCS:
             with open(cls.LOCATION, "w", encoding="utf-8") as out:
                 out.write(contents)

tools/docgen/entry_variables.py

@@ -25,6 +25,7 @@ def _variable_class_to_name(obj: Type[Any]) -> str:
 class EntryVariablesDocGen(DocGen):
 
     LOCATION = Path("docs/source/config_reference/scripting/entry_variables.rst")
+    DOCSTRING_LOCATION = "src/ytdl_sub/entries/script/variable_definitions.py"
 
     @classmethod
     def generate(cls) -> str:

tools/docgen/plugins.py

@@ -2,7 +2,6 @@ import inspect
 from pathlib import Path
 from typing import Any
 from typing import Dict
-from typing import Optional
 from typing import Type
 
 from tools.docgen.docgen import DocGen
@@ -72,6 +71,7 @@ def generate_plugin_docs(name: str, options: Type[OptionsValidator], offset: int
 class PluginsDocGen(DocGen):
 
     LOCATION = Path("docs/source/config_reference/plugins.rst")
+    DOCSTRING_LOCATION = "The respective plugin files under src/ytdl_sub/plugins/"
 
     @classmethod
     def generate(cls):

tools/docgen/scripting_functions.py

@@ -56,6 +56,7 @@ def get_function_docstring(
 class ScriptingFunctionsDocGen(DocGen):
 
     LOCATION = Path("docs/source/config_reference/scripting/scripting_functions.rst")
+    DOCSTRING_LOCATION = "The respective function files under src/ytdl_sub/script/functions/"
 
     @classmethod
     def generate(cls) -> str:

tools/docgen/static_variables.py

@@ -10,6 +10,7 @@ from ytdl_sub.entries.variables.override_variables import SubscriptionVariables
 class StaticVariablesDocGen(DocGen):
 
     LOCATION = Path("docs/source/config_reference/scripting/static_variables.rst")
+    DOCSTRING_LOCATION = "src/ytdl_sub/entries/variables/override_variables.py"
 
     @classmethod
     def generate(cls) -> str: