这是indexloc提供的服务，不要输入任何密码
Skip to content

Migrate markdown doc rewriting into mkdocs hooks #6545

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jan 30, 2024
Merged

Migrate markdown doc rewriting into mkdocs hooks #6545

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b333334
chore: use new github-style admonition
josegonzalez Jan 30, 2024
0c83356
refactor: move docs rewrite into mkdocs hooks
josegonzalez Jan 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
308 changes: 0 additions & 308 deletions contrib/write-mkdocs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@ import os
import pathlib
import shutil
import sys
from collections.abc import Callable

import yaml
from bs4 import BeautifulSoup
Expand Down Expand Up @@ -128,308 +127,6 @@ def generate_nav(src: str, dest: str) -> None:
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
Expand All @@ -438,11 +135,6 @@ def main():
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")
Expand Down
Loading