def generate_from_file_object(
schema_file: TextIO,
result_file: TextIO,
minify: bool = True,
deprecated_from_description: bool = False,
default_from_description: bool = False,
expand_buttons: bool = False,
copy_css: bool = True,
copy_js: bool = True,
link_to_reused_ref: bool = True,
config: GenerationConfiguration = None,
) -> None:
"""Generate the JSON schema documentation from opened file objects for both input and output files. The
result_file should be opened in write mode.
"""
config = config or _get_final_config(
minify=minify,
deprecated_from_description=deprecated_from_description,
default_from_description=default_from_description,
expand_buttons=expand_buttons,
copy_css=copy_css,
copy_js=copy_js,
link_to_reused_ref=link_to_reused_ref,
)
result = generate_from_schema(schema_file, config=config)
copy_css_and_js_to_target(result_file.name, config)
result_file.write(result)
def main(
schema_file: TextIO,
result_file: TextIO,
config_file: TextIO,
config: List[str],
minify: bool,
deprecated_from_description: bool,
default_from_description: bool,
expand_buttons: bool,
copy_css: bool,
copy_js: bool,
link_to_reused_ref: bool,
) -> None:
start = datetime.now()
config = _get_final_config(
minify=minify,
deprecated_from_description=deprecated_from_description,
default_from_description=default_from_description,
expand_buttons=expand_buttons,
copy_css=copy_css,
copy_js=copy_js,
link_to_reused_ref=link_to_reused_ref,
config=config_file,
config_parameters=config,
)
generate_from_file_object(schema_file, result_file, config=config)
duration = datetime.now() - start
print(f"Generated {result_file.name} in {duration}")
def generate_from_filename(
schema_file_name: Union[str, Path],
result_file_name: str,
minify: bool = True,
deprecated_from_description: bool = False,
default_from_description: bool = False,
expand_buttons: bool = False,
copy_css: bool = True,
copy_js: bool = True,
link_to_reused_ref: bool = True,
config: GenerationConfiguration = None,
) -> None:
"""Generate the schema documentation from a filename"""
config = config or _get_final_config(
minify=minify,
deprecated_from_description=deprecated_from_description,
default_from_description=default_from_description,
expand_buttons=expand_buttons,
copy_css=copy_css,
copy_js=copy_js,
link_to_reused_ref=link_to_reused_ref,
)
if isinstance(schema_file_name, str):
schema_file_name = os.path.realpath(schema_file_name)
elif isinstance(schema_file_name, Path):
schema_file_name = str(schema_file_name.resolve())
rendered_schema_doc = generate_from_schema(
schema_file_name,
minify=minify,
deprecated_from_description=deprecated_from_description,
default_from_description=default_from_description,
expand_buttons=expand_buttons,
link_to_reused_ref=link_to_reused_ref,
config=config,
)
copy_css_and_js_to_target(result_file_name, config)
with open(result_file_name, "w", encoding="utf-8") as result_schema_doc:
result_schema_doc.write(rendered_schema_doc)
def generate_from_schema(
schema_file: Union[str, Path, TextIO],
loaded_schemas: Optional[Dict[str, Any]] = None,
minify: bool = True,
deprecated_from_description: bool = False,
default_from_description: bool = False,
expand_buttons: bool = False,
link_to_reused_ref: bool = True,
config: GenerationConfiguration = None,
) -> str:
config = config or _get_final_config(
minify=minify,
deprecated_from_description=deprecated_from_description,
default_from_description=default_from_description,
expand_buttons=expand_buttons,
copy_css=False,
copy_js=False,
link_to_reused_ref=link_to_reused_ref,
)
templates_directory = os.path.join(config.templates_directory, config.template_name)
base_template_path = os.path.join(templates_directory, TEMPLATE_FILE_NAME)
md = markdown2.Markdown(extras=config.markdown_options)
loader = FileSystemLoader(templates_directory)
env = jinja2.Environment(
loader=loader,
extensions=[loopcontrols],
trim_blocks=(config.template_name in ("md", "md_nested")),
lstrip_blocks=(config.template_name in ("md", "md_nested")),
)
if config.template_name in ("md", "md_nested"):
md_template = MarkdownTemplate(config)
md_template.register_jinja(env)
env.filters["markdown"] = (
lambda text: jinja2.Markup(md.convert(text)) if config.description_is_markdown else lambda t: t
)
env.filters["python_to_json"] = jinja_filters.python_to_json
env.filters["get_default"] = (
jinja_filters.get_default_look_in_description if config.default_from_description else jinja_filters.get_default
)
env.filters["get_type_name"] = templating_utils.get_type_name
env.filters["get_description"] = (
jinja_filters.get_description_remove_default
if config.default_from_description
else jinja_filters.get_description
)
env.filters["get_numeric_restrictions_text"] = jinja_filters.get_numeric_restrictions_text
env.filters["get_required_properties"] = jinja_filters.get_required_properties
env.filters["get_first_property"] = jinja_filters.get_first_property
env.filters["get_undocumented_required_properties"] = jinja_filters.get_undocumented_required_properties
env.filters["highlight_json_example"] = jinja_filters.highlight_json_example
env.filters["first_line"] = jinja_filters.first_line
env.tests["combining"] = jinja_filters.is_combining
env.tests["description_short"] = jinja_filters.is_text_short
env.tests["deprecated"] = lambda schema: jinja_filters.deprecated(config, schema)
env.globals["get_local_time"] = jinja_filters.get_local_time
with open(base_template_path, "r") as template_fp:
template = env.from_string(template_fp.read())
if isinstance(schema_file, list):
# Backward compatibility
schema_file = os.path.sep.join(schema_file)
intermediate_schema = build_intermediate_representation(schema_file, config, loaded_schemas)
rendered = template.render(schema=intermediate_schema, config=config)
if minify:
if config.template_name in ("md", "md_nested"):
# remove multiple contiguous empty lines
rendered = re.sub(r"\n\s*\n", "\n\n", rendered)
else:
rendered = htmlmin.minify(rendered)
return rendered