From b24d61d185abca2892f22397bd967415ec3c85e1 Mon Sep 17 00:00:00 2001 From: Jim Date: Thu, 25 Aug 2022 16:13:26 -0400 Subject: [PATCH 1/5] new approach to documenting signatures with variable descriptions --- generate_py5_docs.py | 104 ++++++++++++++++++++++++++++++++++--------- 1 file changed, 83 insertions(+), 21 deletions(-) diff --git a/generate_py5_docs.py b/generate_py5_docs.py index fd6dbcca..47fb62ed 100644 --- a/generate_py5_docs.py +++ b/generate_py5_docs.py @@ -28,6 +28,7 @@ import requests import pandas as pd +import black from generator.docfiles import Documentation @@ -47,6 +48,7 @@ FIRST_SENTENCE_REGEX = re.compile(r'^.*?\.(?=\s)') +PARTITION_SIG_REGEX = re.compile(r'(\w*)\((.*?)\)( ->.*)') REF_COLUMN_STARTS = { 'Sketch': [('lights_camera', 'camera'), ('shape', '')], @@ -91,8 +93,7 @@ {3}{4} {5} -{6} -Updated on {7} +Updated on {6} """ @@ -194,29 +195,89 @@ def format_examples(name, examples): return out -def format_signatures(signatures): - out = '' +# def format_signatures(signatures): +# out = '' - if signatures: - out += '\nSyntax\n------\n\n.. code:: python\n\n' - out += textwrap.indent('\n'.join(signatures), ' ') +# def helper(s): +# return black.format_str(f'def {s}: pass', mode=black.Mode(line_length=80))[4:-11] - return out +# if signatures: +# out += '\nSyntax\n------\n\n.. code:: python\n\n' +# formatted_signatures = [helper(s) for s in signatures] +# has_multi_line_signature = max(len(s.strip().split('\n')) for s in formatted_signatures) > 1 +# out += textwrap.indent(('\n\n' if has_multi_line_signature else '\n').join(formatted_signatures), ' ') + +# return out + + +# def format_parameters(variables): +# out = '' + +# if variables: +# out += '\nParameters\n----------\n\n' +# for var, desc in variables.items(): +# if ':' in var: +# varname, vartype = var.split(':') +# vartype = vartype.replace('\\', '\\\\') +# out += f'* **{varname}**: `{vartype.strip()}` - {desc}\n' +# else: +# out += f'* **{var}**: - {desc}\n' +# out += '\n' +# return out -def format_parameters(variables): + +def tokenize_params(params): + bracket_count = 0 + out = '' + for c in params: + if c == ',' and bracket_count == 0: + yield out.strip() + out = '' + else: + out += c + if c == '[': + bracket_count += 1 + if c == ']': + bracket_count -= 1 + yield out.strip() + + +def format_signatures_variables(signatures, variables): out = '' - if variables: - out += '\nParameters\n----------\n\n' - for var, desc in variables.items(): - if ':' in var: - varname, vartype = var.split(':') - vartype = vartype.replace('\\', '\\\\') - out += f'* **{varname}**: `{vartype.strip()}` - {desc}\n' + if signatures: + new_signatures = [] + for s in signatures: + name, params, ret = PARTITION_SIG_REGEX.match(s).groups() + + if params: + new_params = [] + for param in tokenize_params(params): + if param in variables: + new_params.append((param, variables[param.replace('*', '')])) + else: + new_params.append((param, '')) + + new_params2 = [] + for i, stuff in enumerate(new_params): + # print(stuff) + param, vardesc = stuff + if i < len(new_params) - 1: + new_params2.append(f"{param}, # {vardesc}" if vardesc else f"{param},") + else: + new_params2.append(f"{param} # {vardesc}" if vardesc else param) + + params = '\n'.join(new_params2) + '\n' + line_length = max([len(l) for l in new_params2]) + 5 else: - out += f'* **{var}**: - {desc}\n' - out += '\n' + line_length = 120 + + new_signatures.append(black.format_str(f"def {name}({params}){ret}: pass", mode=black.Mode(line_length=line_length))[4:-11]) + + out += '\nSignatures\n------\n\n.. code:: python\n\n' + has_multi_line_signature = max(len(s.strip().split('\n')) for s in new_signatures) > 1 + out += textwrap.indent(('\n\n' if has_multi_line_signature else '\n').join(new_signatures), ' ') return out @@ -329,8 +390,9 @@ def write_doc_rst_files(dest_dir, py5_doc_ref_dir): title, first_sentence, examples, description, usage, arguments, now_pretty) else: - signatures = format_signatures(doc.signatures) - parameters = format_parameters(doc.variables) + # signatures = format_signatures(doc.signatures) + # parameters = format_parameters(doc.variables) + signatures = format_signatures_variables(doc.signatures, doc.variables) if group in ['Sketch', 'Py5Functions', 'Py5Magics']: title = name elif group == 'Py5Tools': @@ -341,7 +403,7 @@ def write_doc_rst_files(dest_dir, py5_doc_ref_dir): title = f'{title}\n{"=" * len(title)}' doc_rst = DOC_TEMPLATE.format( title, first_sentence, examples, - description, underlying_java_ref, signatures, parameters, now_pretty) + description, underlying_java_ref, signatures, now_pretty) # only write new file if more changed than the timestamp dest_filename = dest_dir / 'reference' / f'{stem.lower()}.rst' From 8c9eecc92960520cbbf2e93de72bbe9799d8eca3 Mon Sep 17 00:00:00 2001 From: Jim Date: Thu, 25 Aug 2022 16:16:47 -0400 Subject: [PATCH 2/5] remove hack code --- generate_py5_docs.py | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/generate_py5_docs.py b/generate_py5_docs.py index 47fb62ed..56fd040b 100644 --- a/generate_py5_docs.py +++ b/generate_py5_docs.py @@ -260,9 +260,7 @@ def format_signatures_variables(signatures, variables): new_params.append((param, '')) new_params2 = [] - for i, stuff in enumerate(new_params): - # print(stuff) - param, vardesc = stuff + for i, (param, vardesc) in enumerate(new_params): if i < len(new_params) - 1: new_params2.append(f"{param}, # {vardesc}" if vardesc else f"{param},") else: From d8fa00f375e522cbf559d0e72713727ba4392e33 Mon Sep 17 00:00:00 2001 From: Jim Date: Thu, 25 Aug 2022 16:19:09 -0400 Subject: [PATCH 3/5] improve code a bit --- generate_py5_docs.py | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/generate_py5_docs.py b/generate_py5_docs.py index 56fd040b..589e8f6c 100644 --- a/generate_py5_docs.py +++ b/generate_py5_docs.py @@ -261,10 +261,8 @@ def format_signatures_variables(signatures, variables): new_params2 = [] for i, (param, vardesc) in enumerate(new_params): - if i < len(new_params) - 1: - new_params2.append(f"{param}, # {vardesc}" if vardesc else f"{param},") - else: - new_params2.append(f"{param} # {vardesc}" if vardesc else param) + maybe_comma = ',' if i < len(new_params) - 1 else '' + new_params2.append(f"{param}{maybe_comma} # {vardesc}" if vardesc else f"{param}{maybe_comma}") params = '\n'.join(new_params2) + '\n' line_length = max([len(l) for l in new_params2]) + 5 From 2d2e958188dafe745e36539311049067fb5f1173 Mon Sep 17 00:00:00 2001 From: Jim Date: Thu, 25 Aug 2022 16:21:25 -0400 Subject: [PATCH 4/5] remove dead code --- generate_py5_docs.py | 34 ---------------------------------- 1 file changed, 34 deletions(-) diff --git a/generate_py5_docs.py b/generate_py5_docs.py index 589e8f6c..eec0d665 100644 --- a/generate_py5_docs.py +++ b/generate_py5_docs.py @@ -195,38 +195,6 @@ def format_examples(name, examples): return out -# def format_signatures(signatures): -# out = '' - -# def helper(s): -# return black.format_str(f'def {s}: pass', mode=black.Mode(line_length=80))[4:-11] - -# if signatures: -# out += '\nSyntax\n------\n\n.. code:: python\n\n' -# formatted_signatures = [helper(s) for s in signatures] -# has_multi_line_signature = max(len(s.strip().split('\n')) for s in formatted_signatures) > 1 -# out += textwrap.indent(('\n\n' if has_multi_line_signature else '\n').join(formatted_signatures), ' ') - -# return out - - -# def format_parameters(variables): -# out = '' - -# if variables: -# out += '\nParameters\n----------\n\n' -# for var, desc in variables.items(): -# if ':' in var: -# varname, vartype = var.split(':') -# vartype = vartype.replace('\\', '\\\\') -# out += f'* **{varname}**: `{vartype.strip()}` - {desc}\n' -# else: -# out += f'* **{var}**: - {desc}\n' -# out += '\n' - -# return out - - def tokenize_params(params): bracket_count = 0 out = '' @@ -386,8 +354,6 @@ def write_doc_rst_files(dest_dir, py5_doc_ref_dir): title, first_sentence, examples, description, usage, arguments, now_pretty) else: - # signatures = format_signatures(doc.signatures) - # parameters = format_parameters(doc.variables) signatures = format_signatures_variables(doc.signatures, doc.variables) if group in ['Sketch', 'Py5Functions', 'Py5Magics']: title = name From 87c874381dbdda117e14301cf7934ff582ec168c Mon Sep 17 00:00:00 2001 From: Jim Date: Fri, 26 Aug 2022 16:08:35 -0400 Subject: [PATCH 5/5] fix matrix docs --- .../api_en/Py5Graphics_apply_matrix.txt | 32 +++++++++---------- .../api_en/Py5Shape_apply_matrix.txt | 32 +++++++++---------- .../Reference/api_en/Sketch_apply_matrix.txt | 32 +++++++++---------- 3 files changed, 48 insertions(+), 48 deletions(-) diff --git a/py5_docs/Reference/api_en/Py5Graphics_apply_matrix.txt b/py5_docs/Reference/api_en/Py5Graphics_apply_matrix.txt index 3f732cc6..d5c83626 100644 --- a/py5_docs/Reference/api_en/Py5Graphics_apply_matrix.txt +++ b/py5_docs/Reference/api_en/Py5Graphics_apply_matrix.txt @@ -12,22 +12,22 @@ apply_matrix(n00: float, n01: float, n02: float, n10: float, n11: float, n12: fl apply_matrix(source: npt.NDArray[np.floating], /) -> None @@ variables -n00: float - numbers which define the 4x4 matrix to be multiplied -n01: float - numbers which define the 4x4 matrix to be multiplied -n02: float - numbers which define the 4x4 matrix to be multiplied -n03: float - numbers which define the 4x4 matrix to be multiplied -n10: float - numbers which define the 4x4 matrix to be multiplied -n11: float - numbers which define the 4x4 matrix to be multiplied -n12: float - numbers which define the 4x4 matrix to be multiplied -n13: float - numbers which define the 4x4 matrix to be multiplied -n20: float - numbers which define the 4x4 matrix to be multiplied -n21: float - numbers which define the 4x4 matrix to be multiplied -n22: float - numbers which define the 4x4 matrix to be multiplied -n23: float - numbers which define the 4x4 matrix to be multiplied -n30: float - numbers which define the 4x4 matrix to be multiplied -n31: float - numbers which define the 4x4 matrix to be multiplied -n32: float - numbers which define the 4x4 matrix to be multiplied -n33: float - numbers which define the 4x4 matrix to be multiplied +n00: float - numeric value in row 0 and column 0 of the matrix +n01: float - numeric value in row 0 and column 1 of the matrix +n02: float - numeric value in row 0 and column 2 of the matrix +n03: float - numeric value in row 0 and column 3 of the matrix +n10: float - numeric value in row 1 and column 0 of the matrix +n11: float - numeric value in row 1 and column 1 of the matrix +n12: float - numeric value in row 1 and column 2 of the matrix +n13: float - numeric value in row 1 and column 3 of the matrix +n20: float - numeric value in row 2 and column 0 of the matrix +n21: float - numeric value in row 2 and column 1 of the matrix +n22: float - numeric value in row 2 and column 2 of the matrix +n23: float - numeric value in row 2 and column 3 of the matrix +n30: float - numeric value in row 3 and column 0 of the matrix +n31: float - numeric value in row 3 and column 1 of the matrix +n32: float - numeric value in row 3 and column 2 of the matrix +n33: float - numeric value in row 3 and column 3 of the matrix source: npt.NDArray[np.floating] - transformation matrix with a shape of 2x3 for 2D transforms or 4x4 for 3D transforms @@ description diff --git a/py5_docs/Reference/api_en/Py5Shape_apply_matrix.txt b/py5_docs/Reference/api_en/Py5Shape_apply_matrix.txt index c8804192..95916cc0 100644 --- a/py5_docs/Reference/api_en/Py5Shape_apply_matrix.txt +++ b/py5_docs/Reference/api_en/Py5Shape_apply_matrix.txt @@ -12,22 +12,22 @@ apply_matrix(n00: float, n01: float, n02: float, n10: float, n11: float, n12: fl apply_matrix(source: npt.NDArray[np.floating], /) -> None @@ variables -n00: float - numbers which define the 4x4 matrix to be multiplied -n01: float - numbers which define the 4x4 matrix to be multiplied -n02: float - numbers which define the 4x4 matrix to be multiplied -n03: float - numbers which define the 4x4 matrix to be multiplied -n10: float - numbers which define the 4x4 matrix to be multiplied -n11: float - numbers which define the 4x4 matrix to be multiplied -n12: float - numbers which define the 4x4 matrix to be multiplied -n13: float - numbers which define the 4x4 matrix to be multiplied -n20: float - numbers which define the 4x4 matrix to be multiplied -n21: float - numbers which define the 4x4 matrix to be multiplied -n22: float - numbers which define the 4x4 matrix to be multiplied -n23: float - numbers which define the 4x4 matrix to be multiplied -n30: float - numbers which define the 4x4 matrix to be multiplied -n31: float - numbers which define the 4x4 matrix to be multiplied -n32: float - numbers which define the 4x4 matrix to be multiplied -n33: float - numbers which define the 4x4 matrix to be multiplied +n00: float - numeric value in row 0 and column 0 of the matrix +n01: float - numeric value in row 0 and column 1 of the matrix +n02: float - numeric value in row 0 and column 2 of the matrix +n03: float - numeric value in row 0 and column 3 of the matrix +n10: float - numeric value in row 1 and column 0 of the matrix +n11: float - numeric value in row 1 and column 1 of the matrix +n12: float - numeric value in row 1 and column 2 of the matrix +n13: float - numeric value in row 1 and column 3 of the matrix +n20: float - numeric value in row 2 and column 0 of the matrix +n21: float - numeric value in row 2 and column 1 of the matrix +n22: float - numeric value in row 2 and column 2 of the matrix +n23: float - numeric value in row 2 and column 3 of the matrix +n30: float - numeric value in row 3 and column 0 of the matrix +n31: float - numeric value in row 3 and column 1 of the matrix +n32: float - numeric value in row 3 and column 2 of the matrix +n33: float - numeric value in row 3 and column 3 of the matrix source: npt.NDArray[np.floating] - transformation matrix with a shape of 2x3 for 2D transforms or 4x4 for 3D transforms @@ description diff --git a/py5_docs/Reference/api_en/Sketch_apply_matrix.txt b/py5_docs/Reference/api_en/Sketch_apply_matrix.txt index 1b8ee390..d40742e5 100644 --- a/py5_docs/Reference/api_en/Sketch_apply_matrix.txt +++ b/py5_docs/Reference/api_en/Sketch_apply_matrix.txt @@ -12,22 +12,22 @@ apply_matrix(n00: float, n01: float, n02: float, n10: float, n11: float, n12: fl apply_matrix(source: npt.NDArray[np.floating], /) -> None @@ variables -n00: float - numbers which define the 4x4 matrix to be multiplied -n01: float - numbers which define the 4x4 matrix to be multiplied -n02: float - numbers which define the 4x4 matrix to be multiplied -n03: float - numbers which define the 4x4 matrix to be multiplied -n10: float - numbers which define the 4x4 matrix to be multiplied -n11: float - numbers which define the 4x4 matrix to be multiplied -n12: float - numbers which define the 4x4 matrix to be multiplied -n13: float - numbers which define the 4x4 matrix to be multiplied -n20: float - numbers which define the 4x4 matrix to be multiplied -n21: float - numbers which define the 4x4 matrix to be multiplied -n22: float - numbers which define the 4x4 matrix to be multiplied -n23: float - numbers which define the 4x4 matrix to be multiplied -n30: float - numbers which define the 4x4 matrix to be multiplied -n31: float - numbers which define the 4x4 matrix to be multiplied -n32: float - numbers which define the 4x4 matrix to be multiplied -n33: float - numbers which define the 4x4 matrix to be multiplied +n00: float - numeric value in row 0 and column 0 of the matrix +n01: float - numeric value in row 0 and column 1 of the matrix +n02: float - numeric value in row 0 and column 2 of the matrix +n03: float - numeric value in row 0 and column 3 of the matrix +n10: float - numeric value in row 1 and column 0 of the matrix +n11: float - numeric value in row 1 and column 1 of the matrix +n12: float - numeric value in row 1 and column 2 of the matrix +n13: float - numeric value in row 1 and column 3 of the matrix +n20: float - numeric value in row 2 and column 0 of the matrix +n21: float - numeric value in row 2 and column 1 of the matrix +n22: float - numeric value in row 2 and column 2 of the matrix +n23: float - numeric value in row 2 and column 3 of the matrix +n30: float - numeric value in row 3 and column 0 of the matrix +n31: float - numeric value in row 3 and column 1 of the matrix +n32: float - numeric value in row 3 and column 2 of the matrix +n33: float - numeric value in row 3 and column 3 of the matrix source: npt.NDArray[np.floating] - transformation matrix with a shape of 2x3 for 2D transforms or 4x4 for 3D transforms @@ description