docs/scripts/gen_python_ref_pages.py at 579095d15268838dddc4890a55215d9fe3b20833 · openml/docs · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
"""
Generate the code reference pages.

based on https://github.com/mkdocstrings/mkdocstrings/blob/33aa573efb17b13e7b9da77e29aeccb3fbddd8e8/docs/recipes.md
but modified for lack of "src/" file structure.

"""

from pathlib import Path
import shutil
import mkdocs_gen_files
import os
import shutil

# Clean a folder completely
def clean_folder(folder: Path):
    if folder.exists() and folder.is_dir():
        shutil.rmtree(folder)

root = Path(__file__).parent.parent
temp_dir = root / "temp_dir" / "python"

# Destination folders
destination_folders = [
    root / "docs" / "python",
    root / "docs" / "examples",
    root / "openml",
]

# Clean all destination folders
for folder in destination_folders:
    clean_folder(folder)

# Source folders
source_folders = [
    temp_dir / "docs",
    temp_dir / "examples",
    temp_dir / "openml",
]

# Copy source to destination
def copy_folders(source_folders: list[Path], destination_folders: list[Path]):
    if len(source_folders) != len(destination_folders):
        raise ValueError("Source and destination lists must have the same length.")

    for src, dest in zip(source_folders, destination_folders):
        if src.exists():
            shutil.copytree(src, dest)

copy_folders(source_folders, destination_folders)

# Generate the reference page docs
nav = mkdocs_gen_files.Nav()
root = Path(__file__).parent.parent
src = root / "openml"
edit_path_root = "/openml/openml-python/blob/docs/mkdoc/"

for path in sorted(src.rglob("*.py")):
    module_path = path.relative_to(root).with_suffix("")
    doc_path = path.relative_to(src).with_suffix(".md")
    full_doc_path = Path("reference", doc_path)

    parts = tuple(module_path.parts)

    if parts[-1] == "__init__":
        parts = parts[:-1]
        doc_path = doc_path.with_name("index.md")
        full_doc_path = full_doc_path.with_name("index.md")
    elif parts[-1] == "__main__":
        continue

    if len(parts) > 1 and not parts[1].startswith("_"):
        nav[parts[1:]] = doc_path.as_posix()

    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
        identifier = ".".join(parts)
        print("::: " + identifier, file=fd)

    mkdocs_gen_files.set_edit_path(full_doc_path, Path(edit_path_root) / path.relative_to(root))

with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
    nav_file.writelines(nav.build_literate_nav())

# Generate the example page index
nav = mkdocs_gen_files.Nav()
examples_src = root / "docs" / "examples"
for path in sorted(examples_src.rglob("*.py")):
    dest_path = path.relative_to(examples_src)

    # Temporary. Renames the ugly folder names
    parts = list(dest_path.parts)
    parts[0] = parts[0].split("_", 1)[-1].capitalize()
    parts = tuple(parts)

    if len(parts) > 1:
        nav[parts] = dest_path.as_posix()
with open(examples_src / "SUMMARY.md", "w") as nav_file:
    nav_file.writelines(nav.build_literate_nav())

# Add icon to the reference pages
content_to_add = "---\nicon: material/bookshelf\n---\n\n"
index_file = root / "docs" / "python" / "index.md"
with open(index_file, "r+") as file:
    original_content = file.read()
    file.seek(0)
    file.write(content_to_add + original_content)