diff --git a/README.md b/README.md index 3b8ae04e34..61f7eecaea 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,5 @@ -> **_NOTE:_** This is an auto-generated file. Please edit docs/docs/en/index.md instead. +[Note]: # (This is an auto-generated file. Please edit docs/docs/en/index.md instead) ---- -hide: - - navigation - - footer ---- FastStream ================ diff --git a/docs/docs.py b/docs/docs.py index f46af32079..07bb68dbf3 100644 --- a/docs/docs.py +++ b/docs/docs.py @@ -4,14 +4,12 @@ from pathlib import Path from shutil import rmtree -import typer import mkdocs.commands.build import mkdocs.commands.serve -from mkdocs.config import load_config - -from expand_markdown import expand_markdown +import typer from create_api_docs import create_api_docs - +from expand_markdown import expand_markdown, remove_lines_between_dashes +from mkdocs.config import load_config IGNORE_DIRS = ("assets", "stylesheets") @@ -26,7 +24,9 @@ EN_DOCS_DIR = DOCS_DIR / "en" EN_INDEX_PATH = EN_DOCS_DIR / "index.md" README_PATH = BASE_DIR.parent / "README.md" -EN_CONTRIBUTING_PATH = EN_DOCS_DIR / "getting-started" / "contributing" / "CONTRIBUTING.md" +EN_CONTRIBUTING_PATH = ( + EN_DOCS_DIR / "getting-started" / "contributing" / "CONTRIBUTING.md" +) CONTRIBUTING_PATH = BASE_DIR.parent / "CONTRIBUTING.md" FASTSTREAM_GEN_DOCS_PATH = BASE_DIR.parent / ".faststream_gen" @@ -165,13 +165,14 @@ def mv(path: str = typer.Argument(...), new_path: str = typer.Argument(...)): @app.command() def update_readme(): - """Update README.md by expanding embeddings in docs/docs/en/index.md - """ + """Update README.md by expanding embeddings in docs/docs/en/index.md""" typer.echo(f"Updating README.md") expand_markdown(input_markdown_path=EN_INDEX_PATH, output_markdown_path=README_PATH) + remove_lines_between_dashes(file_path=README_PATH) + relative_path = os.path.relpath(EN_INDEX_PATH, BASE_DIR.parent) - auto_generated = f"> **_NOTE:_** This is an auto-generated file. Please edit {relative_path} instead.\n\n" + auto_generated = f"[Note]: # (This is an auto-generated file. Please edit {relative_path} instead)\n\n" existing_content = open(README_PATH).read() open(README_PATH, "w").write(auto_generated + existing_content) @@ -179,10 +180,11 @@ def update_readme(): @app.command() def update_contributing(): - """Update CONTRIBUTING.md by expanding embeddings in docs/docs/en/CONTRIBUTING.md - """ + """Update CONTRIBUTING.md by expanding embeddings in docs/docs/en/CONTRIBUTING.md""" typer.echo(f"Updating CONTRIBUTING.md") - expand_markdown(input_markdown_path=EN_CONTRIBUTING_PATH, output_markdown_path=CONTRIBUTING_PATH) + expand_markdown( + input_markdown_path=EN_CONTRIBUTING_PATH, output_markdown_path=CONTRIBUTING_PATH + ) relative_path = os.path.relpath(EN_CONTRIBUTING_PATH, BASE_DIR.parent) auto_generated = f"> **_NOTE:_** This is an auto-generated file. Please edit {relative_path} instead.\n\n" @@ -193,17 +195,20 @@ def update_contributing(): @app.command() def update_faststream_gen_docs(): - """Update docs for faststream gen by expanding all md files in docs/en/docs - """ + """Update docs for faststream gen by expanding all md files in docs/en/docs""" typer.echo("Updating faststream-gen docs") FASTSTREAM_GEN_DOCS_PATH.mkdir(exist_ok=True) md_files = EN_DOCS_DIR.glob("**/*.md") def expand_doc(input_path): relative_path = os.path.relpath(input_path, FASTSTREAM_GEN_DOCS_PATH) - output_path = FASTSTREAM_GEN_DOCS_PATH / relative_path.replace("../docs/docs/en/", "") + output_path = FASTSTREAM_GEN_DOCS_PATH / relative_path.replace( + "../docs/docs/en/", "" + ) output_path.parent.mkdir(parents=True, exist_ok=True) - expand_markdown(input_markdown_path=input_path, output_markdown_path=output_path) + expand_markdown( + input_markdown_path=input_path, output_markdown_path=output_path + ) for md_file in md_files: expand_doc(md_file) @@ -211,8 +216,7 @@ def expand_doc(input_path): @app.command() def build_api_docs(): - """Build api docs for faststream - """ + """Build api docs for faststream""" typer.echo("Updating API docs") create_api_docs(root_path=BASE_DIR, module="faststream") diff --git a/docs/expand_markdown.py b/docs/expand_markdown.py index de4061c03c..85b991082b 100644 --- a/docs/expand_markdown.py +++ b/docs/expand_markdown.py @@ -9,6 +9,7 @@ app = typer.Typer() + def read_lines_from_file(file_path, lines_spec): with open(file_path, "r") as file: all_lines = file.readlines() @@ -18,13 +19,13 @@ def read_lines_from_file(file_path, lines_spec): return "".join(all_lines) selected_lines = [] - line_specs = lines_spec.split(',') + line_specs = lines_spec.split(",") for line_spec in line_specs: if "-" in line_spec: # Handle line ranges (e.g., "1-10") - start, end = map(int, line_spec.split('-')) - selected_lines.extend(all_lines[start - 1:end]) + start, end = map(int, line_spec.split("-")) + selected_lines.extend(all_lines[start - 1 : end]) else: # Handle single line numbers line_number = int(line_spec) @@ -35,7 +36,7 @@ def read_lines_from_file(file_path, lines_spec): def extract_lines(embedded_line): - to_expand_path = re.search('{!>(.*)!}', embedded_line).group(1).strip() + to_expand_path = re.search("{!>(.*)!}", embedded_line).group(1).strip() lines_spec = "" if "[ln:" in to_expand_path: to_expand_path, lines_spec = to_expand_path.split("[ln:") @@ -52,8 +53,13 @@ def extract_lines(embedded_line): @app.command() -def expand_markdown(input_markdown_path: Path = typer.Argument(...), output_markdown_path: Path = typer.Argument(...)): - with open(input_markdown_path, "r") as input_file, open(output_markdown_path, "w") as output_file: +def expand_markdown( + input_markdown_path: Path = typer.Argument(...), + output_markdown_path: Path = typer.Argument(...), +): + with open(input_markdown_path, "r") as input_file, open( + output_markdown_path, "w" + ) as output_file: for line in input_file: # Check if the line does not contain the "{!>" pattern if "{!>" not in line: @@ -63,5 +69,30 @@ def expand_markdown(input_markdown_path: Path = typer.Argument(...), output_mark output_file.write(extract_lines(embedded_line=line)) +def remove_lines_between_dashes(file_path: Path): + with open(file_path, "r") as file: + lines = file.readlines() + + start_dash_index = None + end_dash_index = None + new_lines = [] + + for index, line in enumerate(lines): + if line.strip() == "---": + if start_dash_index is None: + start_dash_index = index + else: + end_dash_index = index + # Remove lines between the two dashes + new_lines = ( + lines[:start_dash_index] + new_lines + lines[end_dash_index + 1 :] + ) + start_dash_index = end_dash_index = None + break # NOTE: Remove this line if you have multiple dash chunks + + with open(file_path, "w") as file: + file.writelines(new_lines) + + if __name__ == "__main__": app()