diff --git a/docs/source/config_reference/scripting/entry_variables.rst b/docs/source/config_reference/scripting/entry_variables.rst index cbd3c0cf..300b558e 100644 --- a/docs/source/config_reference/scripting/entry_variables.rst +++ b/docs/source/config_reference/scripting/entry_variables.rst @@ -1,3 +1,4 @@ + Entry Variables =============== @@ -436,4 +437,4 @@ The upload_date_index padded two digits ytdl_sub_input_url ~~~~~~~~~~~~~~~~~~ -The input URL used in ytdl-sub to create this entry. \ No newline at end of file +The input URL used in ytdl-sub to create this entry. diff --git a/src/ytdl_sub/utils/file_handler.py b/src/ytdl_sub/utils/file_handler.py index 7cf5ef2b..1faf44c3 100644 --- a/src/ytdl_sub/utils/file_handler.py +++ b/src/ytdl_sub/utils/file_handler.py @@ -33,6 +33,15 @@ def get_file_extension(file_name: Path | str) -> str: return file_name.rsplit(".", maxsplit=1)[-1] +def get_md5_hash(contents: str | bytes) -> str: + """ + Helper function to compute md5 hash + """ + if isinstance(contents, str): + contents = contents.encode("utf-8") + return hashlib.md5(contents).hexdigest() + + def get_file_md5_hash(full_file_path: Path | str) -> str: """ Parameters @@ -45,7 +54,7 @@ def get_file_md5_hash(full_file_path: Path | str) -> str: md5 hash of its contents """ with open(full_file_path, "rb") as file: - return hashlib.md5(file.read()).hexdigest() + return get_md5_hash(file.read()) def files_equal(full_file_path_a: Path | str, full_file_path_b: Path | str) -> bool: diff --git a/tests/unit/docgen/__init__.py b/tests/unit/docgen/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/tests/unit/docgen/test_docgen.py b/tests/unit/docgen/test_docgen.py new file mode 100644 index 00000000..e6601702 --- /dev/null +++ b/tests/unit/docgen/test_docgen.py @@ -0,0 +1,11 @@ +from tools.docgen.entry_variables import EntryVariableDocGen +from ytdl_sub.utils.file_handler import get_file_md5_hash +from ytdl_sub.utils.file_handler import get_md5_hash + + +class TestDocGen: + def test_entry_variables_generated(self): + md5_hash = get_file_md5_hash(EntryVariableDocGen.LOCATION) + expected_md5_hash = get_md5_hash(EntryVariableDocGen.generate_and_maybe_write_to_file()) + + assert md5_hash == expected_md5_hash diff --git a/tools/docgen/docgen.py b/tools/docgen/docgen.py new file mode 100644 index 00000000..ecf1ab02 --- /dev/null +++ b/tools/docgen/docgen.py @@ -0,0 +1,32 @@ +from abc import abstractmethod +from pathlib import Path + +REGENERATE_DOCS: bool = True + + +class DocGen: + """ + Home-made auto doc generation + """ + + LOCATION: Path + + @classmethod + @abstractmethod + def generate(cls) -> str: + """ + Generate the docs as a single string + """ + + @classmethod + def generate_and_maybe_write_to_file(cls) -> str: + """ + Maybe writes the docs to their file if the global is set to True, and returns + the generated docs + """ + contents = cls.generate() + if REGENERATE_DOCS: + with open(cls.LOCATION, "w", encoding="utf-8") as out: + out.write(contents) + + return contents diff --git a/tools/docgen/entry_variables.py b/tools/docgen/entry_variables.py index 315be0fc..66cdecfa 100644 --- a/tools/docgen/entry_variables.py +++ b/tools/docgen/entry_variables.py @@ -1,7 +1,9 @@ +from pathlib import Path from typing import Any from typing import Dict from typing import Type +from tools.docgen.docgen import DocGen from tools.docgen.utils import camel_case_to_human from tools.docgen.utils import get_function_docs from tools.docgen.utils import properties @@ -9,33 +11,37 @@ from tools.docgen.utils import section from ytdl_sub.entries.script.variable_definitions import VariableDefinitions -def variable_class_to_name(obj: Type[Any]) -> str: - assert "VariableDefinitions" in obj.__name__, f"{obj.__name__} doesnt have VariableDefinitions" - return ( - camel_case_to_human(obj.__name__) - .replace("Variable Definitions", "Variables") - .replace("Ytdl Sub", "Ytdl-Sub") - ) +class EntryVariableDocGen(DocGen): + LOCATION = Path("docs/source/config_reference/scripting/entry_variables.rst") -def generate_variable_docs() -> str: - docs = section("Entry Variables", level=0) + @classmethod + def _variable_class_to_name(cls, obj: Type[Any]) -> str: + assert ( + "VariableDefinitions" in obj.__name__ + ), f"{obj.__name__} doesnt have VariableDefinitions" + return ( + camel_case_to_human(obj.__name__) + .replace("Variable Definitions", "Variables") + .replace("Ytdl Sub", "Ytdl-Sub") + ) - parent_objs: Dict[str, Type[Any]] = { - variable_class_to_name(obj): obj for obj in VariableDefinitions.__bases__ - } + @classmethod + def generate(cls) -> str: + docs = section("Entry Variables", level=0) - for name in sorted(parent_objs.keys()): - docs += section(name, level=1) + parent_objs: Dict[str, Type[Any]] = { + cls._variable_class_to_name(obj): obj for obj in VariableDefinitions.__bases__ + } - for variable_function_name in properties(parent_objs[name]): - docs += get_function_docs( - function_name=variable_function_name, - obj=parent_objs[name], - level=2, - ) + for name in sorted(parent_objs.keys()): + docs += section(name, level=1) - return docs + for variable_function_name in properties(parent_objs[name]): + docs += get_function_docs( + function_name=variable_function_name, + obj=parent_objs[name], + level=2, + ) - -print(generate_variable_docs()) + return docs diff --git a/tools/docgen/utils.py b/tools/docgen/utils.py index a94fb93c..0daa697a 100644 --- a/tools/docgen/utils.py +++ b/tools/docgen/utils.py @@ -43,8 +43,3 @@ def get_function_docs( docs += inspect.cleandoc(getattr(obj, function_name).__doc__) docs += "\n" return docs - - -def to_out_dir(name: str, docs: str) -> None: - with open(Path("tools") / "docgen" / "out" / name, "w", encoding="utf-8") as out: - out.write(docs)