From 191fa3c1bb9b3ae4a681da161600b73db4e21d30 Mon Sep 17 00:00:00 2001 From: Jesse Bannon Date: Sun, 17 Aug 2025 07:07:25 -0700 Subject: [PATCH] [DOCS] Add warning for auto-generated docs (#1285) --- docs/source/config_reference/plugins.rst | 7 +++++++ .../scripting/entry_variables.rst | 7 +++++++ .../scripting/scripting_functions.rst | 7 +++++++ .../scripting/static_variables.rst | 7 +++++++ tools/docgen/docgen.py | 17 ++++++++++++++++- tools/docgen/entry_variables.py | 1 + tools/docgen/plugins.py | 2 +- tools/docgen/scripting_functions.py | 1 + tools/docgen/static_variables.py | 1 + 9 files changed, 48 insertions(+), 2 deletions(-) diff --git a/docs/source/config_reference/plugins.rst b/docs/source/config_reference/plugins.rst index 95c636e8..1fd114ab 100644 --- a/docs/source/config_reference/plugins.rst +++ b/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 ======= diff --git a/docs/source/config_reference/scripting/entry_variables.rst b/docs/source/config_reference/scripting/entry_variables.rst index 74107134..9ad413e1 100644 --- a/docs/source/config_reference/scripting/entry_variables.rst +++ b/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 =============== diff --git a/docs/source/config_reference/scripting/scripting_functions.rst b/docs/source/config_reference/scripting/scripting_functions.rst index b36573de..77f945ed 100644 --- a/docs/source/config_reference/scripting/scripting_functions.rst +++ b/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 =================== diff --git a/docs/source/config_reference/scripting/static_variables.rst b/docs/source/config_reference/scripting/static_variables.rst index 9a90e761..fb7699b1 100644 --- a/docs/source/config_reference/scripting/static_variables.rst +++ b/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 ================ diff --git a/tools/docgen/docgen.py b/tools/docgen/docgen.py index a021e7ae..f609bf44 100644 --- a/tools/docgen/docgen.py +++ b/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) diff --git a/tools/docgen/entry_variables.py b/tools/docgen/entry_variables.py index df53b13a..4f46c452 100644 --- a/tools/docgen/entry_variables.py +++ b/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: diff --git a/tools/docgen/plugins.py b/tools/docgen/plugins.py index e42718ad..a7f7bed7 100644 --- a/tools/docgen/plugins.py +++ b/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): diff --git a/tools/docgen/scripting_functions.py b/tools/docgen/scripting_functions.py index 9ae519f9..78924ca4 100644 --- a/tools/docgen/scripting_functions.py +++ b/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: diff --git a/tools/docgen/static_variables.py b/tools/docgen/static_variables.py index 254179cc..b8b0c315 100644 --- a/tools/docgen/static_variables.py +++ b/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: