Rooba
/
spaCy
mirror of https://github.com/explosion/spaCy.git
1
1
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add comment markers to only replace auto-generated docs

This commit is contained in:
Ines Montani 2020-08-26 00:03:06 +02:00
parent f10989e8c4
commit 1c958a76c1
1 changed files with 26 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
spacy/cli/project/document.py
View File

@ -19,6 +19,10 @@ inputs have changed."""
INTRO_ASSETS = f"""The following assets are defined by the project. They can INTRO_ASSETS = f"""The following assets are defined by the project. They can
be fetched by running [`spacy project assets`]({DOCS_URL}/api/cli#project-assets) be fetched by running [`spacy project assets`]({DOCS_URL}/api/cli#project-assets)
in the project directory.""" in the project directory."""
# These markers are added to the Markdown and can be used to update the file in
# place if it already exists. Only the auto-generated part will be replaced.
MARKER_START = "<!-- AUTO-GENERATED DOCS START (do not remove) -->"
MARKER_END = "<!-- AUTO-GENERATED DOCS END (do not remove) -->"
@project_cli.command("document") @project_cli.command("document")
@ -29,7 +33,12 @@ def project_document_cli(
no_emoji: bool = Opt(False, "--no-emoji", "-NE", help="Don't use emoji") no_emoji: bool = Opt(False, "--no-emoji", "-NE", help="Don't use emoji")
# fmt: on # fmt: on
): ):
"""Auto-generate a README.md for a project.""" """
Auto-generate a README.md for a project. If the content is saved to a file,
hidden markers are added so you can add custom content before or after the
auto-generated section and only the auto-generated docs will be replaced
when you re-run the command.
"""
project_document(project_dir, output_file, no_emoji=no_emoji) project_document(project_dir, output_file, no_emoji=no_emoji)
@ -39,6 +48,8 @@ def project_document(
is_stdout = str(output_file) == "-" is_stdout = str(output_file) == "-"
config = load_project_config(project_dir) config = load_project_config(project_dir)
md = MarkdownRenderer(no_emoji=no_emoji) md = MarkdownRenderer(no_emoji=no_emoji)
if not is_stdout:
md.add(MARKER_START)
title = config.get("title") title = config.get("title")
description = config.get("description") description = config.get("description")
md.add(md.title(1, f"spaCy Project{f': {title}' if title else ''}", "🪐")) md.add(md.title(1, f"spaCy Project{f': {title}' if title else ''}", "🪐"))
@ -70,12 +81,25 @@ def project_document(
md.add(md.title(3, "Assets", "🗂")) md.add(md.title(3, "Assets", "🗂"))
md.add(INTRO_ASSETS) md.add(INTRO_ASSETS)
md.add(md.table(data, ["File", "Source", "Description"])) md.add(md.table(data, ["File", "Source", "Description"]))
if not is_stdout:
md.add(MARKER_END)
# Output result # Output result
if is_stdout: if is_stdout:
print(md.text) print(md.text)
else: else:
content = md.text
if output_file.exists():
with output_file.open("r", encoding="utf8") as f:
existing = f.read()
if MARKER_START in existing and MARKER_END in existing:
msg.info("Found existing file: only replacing auto-generated docs")
before = existing.split(MARKER_START)[0]
after = existing.split(MARKER_END)[1]
content = f"{before}{content}{after}"
else:
msg.info("Replacing existing file")
with output_file.open("w") as f: with output_file.open("w") as f:
f.write(md.text) f.write(content)
msg.good("Saved project documentation", output_file) msg.good("Saved project documentation", output_file)