From 8d7dba49cbee6a0fc4b77600d1c56cc8d17dcbd1 Mon Sep 17 00:00:00 2001 From: Ludovico Magnocavallo Date: Sat, 29 Jul 2023 11:11:31 +0200 Subject: [PATCH] refactor tfdoc for legibility (#1544) --- tools/check_documentation.py | 8 +++--- tools/tfdoc.py | 52 +++++++++++++++++++----------------- 2 files changed, 32 insertions(+), 28 deletions(-) diff --git a/tools/check_documentation.py b/tools/check_documentation.py index 54d7b28bc9..438fa1b248 100755 --- a/tools/check_documentation.py +++ b/tools/check_documentation.py @@ -73,11 +73,11 @@ def _check_dir(dir_name, exclude_files=None, files=False, show_extra=False): diff = None readme = readme_path.read_text() mod_name = str(readme_path.relative_to(dir_path).parent) - current_doc = tfdoc.get_doc(readme) - current_toc = tfdoc.get_toc(readme) + current_doc = tfdoc.get_tfref_parts(readme) + current_toc = tfdoc.get_toc_parts(readme) if current_doc or current_toc: - new_doc = tfdoc.create_doc(readme_path.parent, files, show_extra, - exclude_files, readme) + new_doc = tfdoc.create_tfref(readme_path.parent, files, show_extra, + exclude_files, readme) new_toc = tfdoc.create_toc(readme) newvars = new_doc.variables newouts = new_doc.outputs diff --git a/tools/tfdoc.py b/tools/tfdoc.py index c81d44f8c9..d17d52d483 100755 --- a/tools/tfdoc.py +++ b/tools/tfdoc.py @@ -235,22 +235,22 @@ def _escape(s): return ''.join(c if c in UNESCAPED else ('&#%s;' % ord(c)) for c in s) -def format_doc(outputs, variables, files, show_extra=False): +def format_tfref(outputs, variables, files, show_extra=False): 'Return formatted document.' buffer = [] if files: buffer += ['', '## Files', ''] - buffer += list(format_files(files)) + buffer += list(format_tfref_files(files)) if variables: buffer += ['', '## Variables', ''] - buffer += list(format_variables(variables, show_extra)) + buffer += list(format_tfref_variables(variables, show_extra)) if outputs: buffer += ['', '## Outputs', ''] - buffer += list(format_outputs(outputs, show_extra)) + buffer += list(format_tfref_outputs(outputs, show_extra)) return '\n'.join(buffer).strip() -def format_files(items): +def format_tfref_files(items): 'Format files table.' items = sorted(items, key=lambda i: i.name) num_modules = sum(len(i.modules) for i in items) @@ -272,7 +272,7 @@ def format_files(items): f' {resources} |' if num_resources else '') -def format_outputs(items, show_extra=True): +def format_tfref_outputs(items, show_extra=True): 'Format outputs table.' if not items: return @@ -290,7 +290,7 @@ def format_outputs(items, show_extra=True): yield format -def format_variables(items, show_extra=True): +def format_tfref_variables(items, show_extra=True): 'Format variables table.' if not items: return @@ -342,7 +342,7 @@ def create_toc(readme): # replace functions -def get_doc(readme): +def get_tfref_parts(readme): 'Check if README file is marked, and return current doc.' m = re.search('(?sm)%s(.*)%s' % (MARK_BEGIN, MARK_END), readme) if not m: @@ -350,7 +350,7 @@ def get_doc(readme): return {'doc': m.group(1).strip(), 'start': m.start(), 'end': m.end()} -def get_toc(readme): +def get_toc_parts(readme): 'Check if README file is marked, and return current toc.' t = re.search('(?sm)%s(.*)%s' % (TOC_BEGIN, TOC_END), readme) if not t: @@ -358,7 +358,7 @@ def get_toc(readme): return {'toc': t.group(1).strip(), 'start': t.start(), 'end': t.end()} -def get_doc_opts(readme): +def get_tfref_opts(readme): 'Check if README file is setting options via a mark, and return options.' m = MARK_OPTS_RE.search(readme) opts = {} @@ -373,11 +373,11 @@ def get_doc_opts(readme): return opts -def create_doc(module_path, files=False, show_extra=False, exclude_files=None, - readme=None): +def create_tfref(module_path, files=False, show_extra=False, exclude_files=None, + readme=None): if readme: # check for overrides in doc - opts = get_doc_opts(readme) + opts = get_tfref_opts(readme) files = opts.get('files', files) show_extra = opts.get('show_extra', show_extra) try: @@ -386,7 +386,7 @@ def create_doc(module_path, files=False, show_extra=False, exclude_files=None, mod_outputs = list(parse_outputs(module_path, exclude_files)) except (IOError, OSError) as e: raise SystemExit(e) - doc = format_doc(mod_outputs, mod_variables, mod_files, show_extra) + doc = format_tfref(mod_outputs, mod_variables, mod_files, show_extra) return Document(doc, mod_files, mod_variables, mod_outputs) @@ -398,10 +398,12 @@ def get_readme(readme_path): raise SystemExit(f'Error opening README {readme_path}: {e}') -def render_doc(readme, doc): +def render_tfref(readme, doc): 'Replace document in module\'s README.md file.' - result = get_doc(readme) - if not result or doc == result['doc']: + result = get_tfref_parts(readme) + if not result: + raise SystemExit(f'Mark not found in README') + if doc == result['doc']: return readme return '\n'.join([ readme[:result['start']].rstrip(), @@ -414,7 +416,7 @@ def render_doc(readme, doc): def render_toc(readme, toc): 'Replace toc in module\'s README.md file.' - result = get_toc(readme) + result = get_toc_parts(readme) if not result or toc == result['toc']: return readme return '\n'.join([ @@ -434,23 +436,25 @@ def render_toc(readme, toc): @click.option('--files/--no-files', default=False) @click.option('--replace/--no-replace', default=True) @click.option('--show-extra/--no-show-extra', default=False) +@click.option('--toc-only', is_flag=True, default=False) def main(module_path=None, exclude_file=None, files=False, replace=True, - show_extra=True): + show_extra=True, toc_only=False): 'Program entry point.' readme_path = os.path.join(module_path, 'README.md') readme = get_readme(readme_path) - doc = create_doc(module_path, files, show_extra, exclude_file, readme) + if not toc_only: + doc = create_tfref(module_path, files, show_extra, exclude_file, readme) + readme = render_tfref(readme, doc.content) toc = create_toc(readme) - tmp = render_doc(readme, doc.content) - final = render_toc(tmp, toc) + readme = render_toc(readme, toc) if replace: try: with open(readme_path, 'w') as f: - f.write(final) + f.write(readme) except (IOError, OSError) as e: raise SystemExit(f'Error replacing README {readme_path}: {e}') else: - print(final) + print(readme) if __name__ == '__main__':