mik-laj commented on issue #11077: URL: https://github.com/apache/airflow/issues/11077#issuecomment-700880559
@flvndh Yes. We use pre-commit checks to update README.md files Example below: https://github.com/apache/airflow/blob/ebd71508627e68f6c35f1aff2d03b4569de80f4b/.pre-commit-config.yaml#L235-L240 Sphinx does not generate MD files, but HTML files, so your original proposal assumed the workflow would be as follows. 1. Users run Sphinx 2. Sphinx load Jinja extension 3. Sphinx load values.schema.json 4. Jinja extension renders RST page based on values.schema.json file 5. Sphinx render RST as HTML 6. User has an HTML file and can publish them. Since the rest of the documentation is in README.md. And I don't see the need to move it, only we will have one file with reference documentation. I think this can be simplified and we can write a simple Python script that will load a template with HTML code, load the configuration, and generate reference documentation. 1. User run custom python script 2. Script load Jinja and HTML template 3. Jinja renders an HTML file. 4. User has an HTML file and can publish them. It will look a bit like the code below. ```python TPL_PATH = .... TEMPLATE_LOADER = jinja2.FileSystemLoader(searchpath=TPL_PATH) TEMPLATE_ENV = jinja2.Environment( loader=TEMPLATE_LOADER, undefined=jinja2.StrictUndefined, trim_blocks=True, lstrip_blocks=True ) TEMPLATE_CACHES: Dict[str, Any] = {} def render_template(template_name: str, *args, **kwargs) -> str: """Render Jinja template""" if template_name not in TEMPLATE_CACHES: template = TEMPLATE_ENV.get_template(template_name) TEMPLATE_CACHES[template_name] = template content: str = TEMPLATE_CACHES[template_name].render(*args, **kwargs) return content def load_schema(schema_filepath: str) -> str: with open(schema_filepath) as json_file return json.load(json_file) TEMPLATE_PATH = "./helm-refernece-docs.html" SCHEMA_PATH = "../values.schema.json" OUTPUT_PATH = "../dist/reference-docs.html" with file(output_filepath, "w") as output_file: schema = load_schema(SCHEMA_PATH) output_file.wirte(render_template(TEMPLATE_NAME, schema=schemaa)) print("Refenrece docs generated to {output_filepath}") ``` While writing this code, I found one cool tool that can help us too - [j2-cli](https://github.com/kolypto/j2cli) Then generating documentation may look much easier. ``` j2 refernece-docs.j2 ../values.schema.json ``` You also ask if it should be a markdown or HTML. I don't have strong requirements on this, but I think HTML will be much more flexible. We can achieve a much better quality and user-experience than in pure markdown. On the other hand, if we use markdown, our documentation will always be updated thanks to pre-commit checks. I prefer HTML a little more, but I think if we use `j2-cli` it will be easy to support both formats. ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected]
