mirror of
https://github.com/dokku/dokku.git
synced 2025-12-16 12:07:45 +01:00
cf0623407c
This will allow us to add little icons to various parts of the docs to denote when something is for a particular scheduler only.
456 lines
14 KiB
Python
456 lines
14 KiB
Python
#!/usr/bin/env python
|
|
import os
|
|
import pathlib
|
|
import shutil
|
|
import sys
|
|
from collections.abc import Callable
|
|
|
|
import yaml
|
|
from bs4 import BeautifulSoup
|
|
|
|
|
|
def get_nav_from_selector(soup: BeautifulSoup, selector: str, docs_dir: str):
|
|
"""
|
|
Generates navigation from template file
|
|
"""
|
|
navigation = []
|
|
header_name = ""
|
|
for anchor in soup.select(selector):
|
|
classes = anchor.get("class", [])
|
|
if classes is None:
|
|
continue
|
|
|
|
if "disabled" in classes:
|
|
header_name = anchor.text
|
|
navigation.append({header_name: []})
|
|
|
|
href = anchor.get("href", "")
|
|
if href is None:
|
|
continue
|
|
|
|
href = str(href)
|
|
if href == "#":
|
|
continue
|
|
|
|
url = href.replace("{{NAME}}", "")
|
|
filename = url.replace("http://progrium.viewdocs.io/dokku/", "")
|
|
filename = filename.replace("http://dokku.viewdocs.io/dokku/", "")
|
|
filename = filename.strip("/") + ".md"
|
|
filename = filename.removeprefix("dokku/")
|
|
|
|
ignore_errors_for = [
|
|
"getting-started/installation.md",
|
|
"getting-started/upgrading.md",
|
|
]
|
|
if not os.path.exists(docs_dir + "/" + filename):
|
|
if filename not in ignore_errors_for:
|
|
print("error fetching markdown file:", filename)
|
|
continue
|
|
|
|
for nav in navigation:
|
|
if header_name in nav:
|
|
if filename == "getting-started/installation.md":
|
|
child_dir = "getting-started/install/"
|
|
children = os.listdir(docs_dir + "/" + child_dir)
|
|
children = [child_dir + c for c in children]
|
|
children.sort()
|
|
children.insert(0, "getting-started/advanced-installation.md")
|
|
if os.path.exists(docs_dir + "/" + filename):
|
|
children.insert(0, filename)
|
|
else:
|
|
children.insert(0, "getting-started/installation/index.md")
|
|
nav[header_name].append(
|
|
{
|
|
"Getting Started with Dokku": children,
|
|
}
|
|
)
|
|
continue
|
|
|
|
if filename == "getting-started/upgrading.md":
|
|
child_dir = "appendices/"
|
|
children = os.listdir(docs_dir + "/" + child_dir)
|
|
|
|
children.sort(
|
|
key=lambda x: list(map(int, x.split("-")[0].split("."))),
|
|
reverse=True,
|
|
)
|
|
children = [child_dir + c for c in children]
|
|
if os.path.exists(docs_dir + "/" + filename):
|
|
children.insert(0, filename)
|
|
else:
|
|
children.insert(0, "getting-started/upgrading/index.md")
|
|
nav[header_name].append(
|
|
{
|
|
"Upgrading": children,
|
|
}
|
|
)
|
|
continue
|
|
|
|
nav[header_name].append(filename)
|
|
return navigation
|
|
|
|
|
|
def generate_nav(src: str, dest: str) -> None:
|
|
"""
|
|
Writes out navigation information to the mkdocs yaml file
|
|
"""
|
|
navigation = []
|
|
repo_dir = pathlib.Path(__file__).parent.parent.resolve()
|
|
docs_dir = str(repo_dir) + "/docs"
|
|
with open(docs_dir + "/template.html", encoding="utf-8") as response:
|
|
soup = BeautifulSoup(response, "html.parser")
|
|
selectors = [
|
|
".container .row .list-group a",
|
|
".container-fluid .row .list-group a",
|
|
]
|
|
for selector in selectors:
|
|
navigation = get_nav_from_selector(soup, selector, docs_dir)
|
|
if len(navigation) > 0:
|
|
break
|
|
|
|
if len(navigation) == 0:
|
|
print("No navigation found")
|
|
sys.exit(1)
|
|
|
|
with open(src, encoding="utf-8") as handler:
|
|
data = yaml.unsafe_load(handler)
|
|
data["nav"] = [
|
|
{"Docs": navigation},
|
|
{"Pro": "https://pro.dokku.com/docs/getting-started/"},
|
|
{"Blog": "https://dokku.com/blog/"},
|
|
{"Tutorials": "https://dokku.com/tutorials/"},
|
|
{
|
|
"Purchase Dokku Pro": "https://dokku.dpdcart.com/cart/add?product_id=217344&method_id=236878"
|
|
},
|
|
]
|
|
|
|
with open(dest, mode="wt", encoding="utf-8") as handler:
|
|
yaml.dump(data, handler)
|
|
|
|
|
|
def modify_content_noop(lines: list[str], _) -> tuple[list[str], bool]:
|
|
"""
|
|
Simply returns the lines as is
|
|
"""
|
|
modified = False
|
|
updated_lines = []
|
|
for line in lines:
|
|
updated_lines.append(line)
|
|
return updated_lines, modified
|
|
|
|
|
|
def modify_content_links(lines: list[str], filename: str) -> tuple[list[str], bool]:
|
|
"""
|
|
Modifies links to be relative instead of absolute
|
|
"""
|
|
filename = filename.replace("/usr/src/source/docs/", "")
|
|
parts = filename.split("/")
|
|
parts.pop()
|
|
replacement = "](" + "/".join([".." for _ in parts]) + "/"
|
|
modified = False
|
|
updated_lines = []
|
|
for line in lines:
|
|
if "](/docs/" in line:
|
|
line = line.replace("](/docs/", replacement)
|
|
modified = True
|
|
|
|
updated_lines.append(line)
|
|
return updated_lines, modified
|
|
|
|
|
|
def modify_content_stripspace(lines: list[str], _) -> tuple[list[str], bool]:
|
|
"""
|
|
Removes trailing whitespace from each line
|
|
"""
|
|
modified = False
|
|
updated_lines = []
|
|
for line in lines:
|
|
line = line.rstrip()
|
|
updated_lines.append(line)
|
|
return updated_lines, modified
|
|
|
|
|
|
def modify_content_inject_newlines(lines: list[str], _) -> tuple[list[str], bool]:
|
|
"""
|
|
Ensures every line has a trailing newline character
|
|
"""
|
|
modified = False
|
|
updated_lines = []
|
|
for line in lines:
|
|
updated_lines.append(line.rstrip() + "\n")
|
|
return updated_lines, modified
|
|
|
|
|
|
def is_github_new(line: str, next_line: str | None) -> bool:
|
|
"""
|
|
Checks if a given line is a github "new as of" admonition
|
|
"""
|
|
if not next_line:
|
|
return False
|
|
|
|
return line.startswith("> [!IMPORTANT]") and "new as of" in next_line.lower()
|
|
|
|
|
|
def is_github_note(line: str) -> bool:
|
|
"""
|
|
Checks if a given line is a github "note" admonition
|
|
"""
|
|
return line.startswith("> [!NOTE]")
|
|
|
|
|
|
def is_github_warning(line: str) -> bool:
|
|
"""
|
|
Checks if a given line is a github "warning" admonition
|
|
"""
|
|
return line.startswith("> [!WARNING]")
|
|
|
|
|
|
def is_info(line: str) -> bool:
|
|
"""
|
|
Checks if a given line is an "info" admonition
|
|
"""
|
|
return line.startswith("> ")
|
|
|
|
|
|
def is_new(line: str) -> bool:
|
|
"""
|
|
Checks if a given line is a "new as of" admonition
|
|
"""
|
|
return line.startswith("> ") and "new as of" in line.lower()
|
|
|
|
|
|
def is_note(line: str) -> bool:
|
|
"""
|
|
Checks if a given line is a "note" admonition
|
|
"""
|
|
return line.startswith("> Note:")
|
|
|
|
|
|
def is_warning(line: str) -> bool:
|
|
"""
|
|
Checks if a given line is a "warning" admonition
|
|
"""
|
|
return line.startswith("> Warning:")
|
|
|
|
|
|
def modify_content_admonition(lines: list[str], _) -> tuple[list[str], bool]:
|
|
"""
|
|
Applies adminition info to each line in the output
|
|
"""
|
|
modified = False
|
|
updated_lines = []
|
|
admonition_lines = []
|
|
is_admonition = False
|
|
replace_new_in_next_line = False
|
|
for index, line in enumerate(lines):
|
|
next_line: str | None = None
|
|
if index + 1 < len(lines):
|
|
next_line = lines[index + 1]
|
|
|
|
if replace_new_in_next_line:
|
|
line = line.replace("New as of", "Introduced in")
|
|
line = line.replace("new as of", "introduced in")
|
|
replace_new_in_next_line = False
|
|
|
|
if is_github_new(line, next_line):
|
|
line = line.replace("> [!IMPORTANT]", '!!! tip "New"')
|
|
is_admonition = True
|
|
admonition_lines.append(line)
|
|
admonition_lines.append("")
|
|
replace_new_in_next_line = True
|
|
elif is_github_note(line):
|
|
line = line.replace("> [!NOTE]", '!!! note "Note"')
|
|
is_admonition = True
|
|
admonition_lines.append(line)
|
|
admonition_lines.append("")
|
|
elif is_github_warning(line):
|
|
line = line.replace("> [!WARNING]", '!!! warning "Warning"')
|
|
is_admonition = True
|
|
admonition_lines.append(line)
|
|
admonition_lines.append("")
|
|
elif is_new(line):
|
|
print("is_new")
|
|
line = line.replace("> ", '!!! tip "New"\n\n ')
|
|
line = line.replace("New as of", "Introduced in")
|
|
line = line.replace("new as of", "introduced in")
|
|
is_admonition = True
|
|
admonition_lines.append(line)
|
|
elif is_note(line):
|
|
print("is_note")
|
|
line = line.replace("> Note: ", '!!! note "Note"\n\n ')
|
|
is_admonition = True
|
|
admonition_lines.append(line)
|
|
elif is_warning(line):
|
|
print("is_warning")
|
|
line = line.replace("> Warning: ", '!!! warning "Warning"\n\n ')
|
|
is_admonition = True
|
|
admonition_lines.append(line)
|
|
elif is_info(line):
|
|
if not is_admonition:
|
|
line = line.replace("> ", '!!! info "Info"\n\n ')
|
|
elif line in [">", "> "]:
|
|
line = ""
|
|
else:
|
|
line = " " + line.removeprefix("> ")
|
|
is_admonition = True
|
|
admonition_lines.append(line)
|
|
elif is_admonition and line in [">", "> "]:
|
|
line = ""
|
|
admonition_lines.append(line)
|
|
elif is_admonition and line.startswith("> "):
|
|
line = " " + line.removeprefix("> ")
|
|
admonition_lines.append(line)
|
|
elif line == "":
|
|
is_admonition = False
|
|
if len(admonition_lines) > 0:
|
|
modified = True
|
|
updated_lines.extend(admonition_lines)
|
|
admonition_lines = []
|
|
updated_lines.append("")
|
|
else:
|
|
updated_lines.append(line)
|
|
return updated_lines, modified
|
|
|
|
|
|
def is_shell_codeblock_start(line: str) -> bool:
|
|
"""
|
|
Checks to see if a line starts a codeblock
|
|
"""
|
|
return line == "```shell"
|
|
|
|
|
|
def modify_content_terminal_example(lines: list[str], _) -> tuple[list[str], bool]:
|
|
"""
|
|
Modifies content so that terminal output is shown appropriately
|
|
"""
|
|
modified = False
|
|
updated_lines = []
|
|
command_block = []
|
|
example_block = []
|
|
in_command_block = False
|
|
in_example_block = False
|
|
previous_block = ""
|
|
next_line_must_be = None
|
|
for line in lines:
|
|
if is_shell_codeblock_start(line):
|
|
command_block.append(line)
|
|
modified = True
|
|
in_command_block = True
|
|
continue
|
|
elif in_command_block:
|
|
command_block.append(line)
|
|
if line == "```":
|
|
in_command_block = False
|
|
previous_block = "command_block"
|
|
next_line_must_be = ""
|
|
continue
|
|
elif line == "```":
|
|
if previous_block == "":
|
|
updated_lines.append(line)
|
|
continue
|
|
if previous_block == "command_block":
|
|
example_block.append(line)
|
|
|
|
if in_example_block:
|
|
previous_block = ""
|
|
in_example_block = False
|
|
updated_lines.append('=== "Shell"')
|
|
updated_lines.append("")
|
|
for command_line in command_block:
|
|
updated_lines.append(f" {command_line}")
|
|
command_block = []
|
|
|
|
updated_lines.append("")
|
|
updated_lines.append('=== "Output"')
|
|
updated_lines.append("")
|
|
for example_line in example_block:
|
|
updated_lines.append(f" {example_line}")
|
|
example_block = []
|
|
else:
|
|
in_example_block = True
|
|
continue
|
|
elif previous_block == "command_block":
|
|
if next_line_must_be is None:
|
|
if in_example_block:
|
|
example_block.append(line)
|
|
else:
|
|
updated_lines.extend(command_block)
|
|
updated_lines.append("")
|
|
updated_lines.append(line)
|
|
command_block = []
|
|
previous_block = ""
|
|
continue
|
|
if next_line_must_be == "":
|
|
if line == "":
|
|
next_line_must_be = None
|
|
continue
|
|
|
|
updated_lines.append(line)
|
|
|
|
if len(command_block) > 0:
|
|
updated_lines.extend(command_block)
|
|
|
|
return updated_lines, modified
|
|
|
|
|
|
def update_markdown(src):
|
|
"""
|
|
Updates all markdown files to be mkdocs compatible
|
|
"""
|
|
markdown_files = []
|
|
allowed_extensions = [".md"]
|
|
for subdir, _, files in os.walk(src):
|
|
for file in files:
|
|
ext = os.path.splitext(file)[-1].lower()
|
|
file_path = os.path.join(subdir, file)
|
|
if ext in allowed_extensions:
|
|
markdown_files.append(file_path)
|
|
|
|
modifiers: list[Callable[[list[str], str], tuple[list[str], bool]]] = [
|
|
modify_content_noop,
|
|
modify_content_links,
|
|
modify_content_stripspace,
|
|
modify_content_admonition,
|
|
modify_content_terminal_example,
|
|
modify_content_inject_newlines,
|
|
]
|
|
|
|
for file in markdown_files:
|
|
is_modified = False
|
|
lines = []
|
|
with open(file, "r", encoding="utf-8") as handler:
|
|
lines = handler.readlines()
|
|
for modifier in modifiers:
|
|
lines, modified = modifier(lines, file)
|
|
if modified:
|
|
is_modified = True
|
|
|
|
if is_modified:
|
|
with open(file, "w", encoding="utf-8") as handler:
|
|
handler.writelines(lines)
|
|
|
|
|
|
def main():
|
|
"""
|
|
Main command that performs doc manipulation
|
|
"""
|
|
print("----> Copying mkdocs.yml")
|
|
print(" Generating navigation")
|
|
generate_nav("/usr/src/source/mkdocs.yml", "/usr/src/app/mkdocs.yml")
|
|
|
|
print("----> Copying docs folder")
|
|
update_markdown(
|
|
"/usr/src/source/docs",
|
|
)
|
|
|
|
if os.path.exists("/usr/src/app/docs"):
|
|
print(" Removing old docs folder")
|
|
shutil.rmtree("/usr/src/app/docs")
|
|
|
|
print(" Performing copy")
|
|
shutil.copytree("/usr/src/source/docs", "/usr/src/app/docs")
|
|
|
|
|
|
if __name__ == "__main__":
|
|
main()
|