Improve output of diagram + BOM as technical drawing #239

formatc1702 · 2021-08-25T19:02:43Z

New version of #74.

Reason for new PR:

74 was based on the original branch for Add basic options and metadata #214, called feature/metadata
# 214 was then squash-merged onto dev.
Deleting feature/metadata (since it was no longer needed for # 214) without changing # 74's base first, cause it to auto-close, with no way to re-open

formatc1702 · 2021-08-26T17:25:48Z

This PR is ready for review. I have been using this feature and the included DIN 6771 template files for quite a while and I am very pleased with the results.

In the interest of not delaying the merge too much, I would request to address the following minor issues as separate PRs:

Optimization of the HTML templates themselves
Dealing with resolving template file paths specified in the prepend YAML file.
- I would like to fix this together with the related issue from the comment in #189 afterwards
- The newly added smart_file_resolve() may help fix both issues
Parsing any color/font specs from the options section of the YAML and applying them to the HTML
I have purposely only edited demo02.yml to include metadata and template specs, but not demo01.yml, so as to keep 01 as simple as possible.

kvid

This preliminary review is only based on inspection of changes, not testing.
Consider also replacing all keywords from the template in one pass to avoid replacement of replacements (and to increase efficiency), e.g. like in the lead answer here: https://stackoverflow.com/questions/6116978/how-to-replace-multiple-substrings-of-a-string
Have you considered supporting an optional default value of each keyword in templates? (e.g. something like this: )

src/wireviz/wv_helper.py

src/wireviz/wv_html.py

src/wireviz/templates/din-6771.html

src/wireviz/templates/simple.html

formatc1702 · 2021-09-27T19:20:06Z

This preliminary review is only based on inspection of changes, not testing.

Thanks, I will incorporate some of your changes soon and wait for some testing.

Consider also replacing all keywords from the template in one pass to avoid replacement of replacements (and to increase efficiency), e.g. like in the lead answer here: https://stackoverflow.com/questions/6116978/how-to-replace-multiple-substrings-of-a-string

👍

Have you considered supporting an optional default value of each keyword in templates? (e.g. something like this: )

Sounds like a nice follow-up PR.

src/wireviz/wv_html.py

src/wireviz/wv_helper.py

src/wireviz/wv_html.py

Moved metadata and options info further down, so that the core functionality (connectors, cables, connection sets) comes first.

- Use pin names instead of pin indices, until the last moment when generating the ports for the GraphViz nodes - `Harness.add_mate_pin()` now uses pin names - Remove unused `if is_arrow()` check from `Harness.connect()` - Consolidate calling of `Connector.activate_pin()` to prevent subtle bugs - Call it from `connect()` and `add_mate_pin()` - No longer call it from `create_graph()` - Misc. other tuning

Use `output_formats` parameter to specify which *files* to output to disk, Use `return_types` parameter to specify which objects to return to a calling Python script

…nput

…aths

kvid

I like this concept of templates and the generic replacement rules. However, I have included a few more suggestions.

kvid · 2021-12-19T18:16:39Z

src/wireviz/wv_helper.py

+        for possible_path in possible_paths:
+            resolved_path = (possible_path / filename).resolve()


To improve readability slightly, I suggest the shorter path as loop variable in this case as it is not ambiguous, and easier to distinguish from possible_paths:

Suggested change

for possible_path in possible_paths:

resolved_path = (possible_path / filename).resolve()

for path in possible_paths:

resolved_path = (path / filename).resolve()

kvid · 2021-12-19T18:30:36Z

src/wireviz/templates/simple.html

+    }
+
+  </style>
+</head><body style="font-family:<!-- %fontname% -->;background-color:<!-- %bgcolor% -->">


Have you considered moving these two style entries of the body tag into a new body entry in the upper part of the style tag above, as it is in the DIN-6771 template?

Or maybe these style entries are intentionally defined in two different ways in the two templates to demonstrate both ways?

kvid · 2022-01-08T00:23:18Z

src/wireviz/wv_helper.py

+            if resolved_path.exists():
+                return resolved_path
+        else:
+            raise Exception(f'{filename} was not found in any of the following locations: \n' +
+                            '\n'.join([str(x) for x in possible_paths]))


The function name smart_file_resolve() indicate that it will only resolve a regular file (or maybe a symbolic link pointing to a regular file). If that's the intention, then I suggest testing is_file() to avoid accepting e.g. a directory with the same name, and also explain that a file with this name was not found in the exception case.

I also recommend double quotes around the filename to increase readability when the filename might contain spaces. If it's really important to avoid such quotes when the filename doesn't contain spaces, then I suggest a new helper function: def quote_if_needed(name: str) -> str: return f'"{name}"' if ' ' in name else name

Suggested change

if resolved_path.exists():

return resolved_path

else:

raise Exception(f'{filename} was not found in any of the following locations: \n' +

'\n'.join([str(x) for x in possible_paths]))

if resolved_path.is_file():

return resolved_path

else:

raise Exception(f'A file named "{filename}" was not found in any of the following locations:\n' +

'\n'.join([str(x) for x in possible_paths]))

kvid · 2022-01-08T00:58:45Z

src/wireviz/wv_html.py

+        templatefile = smart_file_resolve(f'{templatename}.html', [Path(filename).parent, Path(__file__).parent / 'templates'])
+    else:
+        # fall back to built-in simple template if no template was provided
+        templatefile = Path(__file__).parent / 'templates/simple.html'


I suggest defining STD_TEMPLATES = Path(__file__).parent / 'templates' in the global scope together with other global constants (consider also alternative constant names for a better fit with other constants) and use it here:

Suggested change

templatefile = smart_file_resolve(f'{templatename}.html', [Path(filename).parent, Path(__file__).parent / 'templates'])

else:

# fall back to built-in simple template if no template was provided

templatefile = Path(__file__).parent / 'templates/simple.html'

templatefile = smart_file_resolve(f'{templatename}.html', [Path(filename).parent, STD_TEMPLATES])

else:

# fall back to built-in simple template if no template was provided

templatefile = STD_TEMPLATES / 'simple.html'

kvid · 2022-01-08T01:26:32Z

src/wireviz/wv_html.py

+    with open_file_read(f'{filename}.svg') as file:
+        svgdata = re.sub(
+            '^<[?]xml [^?>]*[?]>[^<]*<!DOCTYPE [^>]*>',
+            '<!-- XML and DOCTYPE declarations from SVG file removed -->',


Consider including the name of the embedded file in the leading comment for easier debugging:

Suggested change

'',

f'',

kvid · 2022-01-08T01:26:38Z

src/wireviz/wv_html.py

+        svgdata = re.sub(
+            '^<[?]xml [^?>]*[?]>[^<]*<!DOCTYPE [^>]*>',
+            '<!-- XML and DOCTYPE declarations from SVG file removed -->',
+            file.read(), 1)


Consider also tagging the end of the embedded file:

Suggested change

file.read(), 1)

file.read(), 1) + f''

kvid · 2022-01-08T02:00:55Z

src/wireviz/wv_html.py

+    # generate BOM contents
+    bom_contents = []
+    for row in bom[1:]:
+        row_html = '  <tr>\n'


Consider tagging each BOM row with the unique ID to allow cross referencing to each BOM entry:

Suggested change

row_html = ' <tr>\n'

row_html = f' <tr id="{row[0]}">\n'

Maybe it's even better with a prefix to reduce the probability of any future ID conflicts:

Suggested change

row_html = ' <tr>\n'

row_html = f' <tr id="bom-e{row[0]}">\n'

kvid · 2022-01-08T02:34:09Z

src/wireviz/wv_html.py

+            if isinstance(contents, (str, int, float)):
+                replacements[f'<!-- %{item}% -->'] = html_line_breaks(str(contents))


In case of a name collision between a metadata entry and any of the simple replacements above, the metadata entry will overwrite the simple replacement. Is this intentional? It enables overriding e.g. the generator version string.

kvid · 2022-01-08T03:02:54Z

src/wireviz/wv_html.py

-        for row in listy[1:]:
-            file.write(' <tr>\n')
-            for i, item in enumerate(row):
-                item_str = item.replace('\u00b2', '&sup2;')


I cannot find this replacement in your new code. Is it obsolete and no longer needed, or handled in a different way?

formatc1702 mentioned this pull request Aug 25, 2021

[meta] Collaborator discussion #101

Open

formatc1702 force-pushed the feature/technical-drw branch from 6f56fcd to 627096f Compare August 26, 2021 17:16

formatc1702 marked this pull request as ready for review August 26, 2021 17:18

formatc1702 requested a review from kvid August 26, 2021 17:26

formatc1702 mentioned this pull request Aug 26, 2021

Embed images in SVG output #189

Merged

kvid requested changes Sep 25, 2021

View reviewed changes

src/wireviz/wv_helper.py Outdated Show resolved Hide resolved

src/wireviz/wv_html.py Outdated Show resolved Hide resolved

src/wireviz/templates/din-6771.html Outdated Show resolved Hide resolved

src/wireviz/templates/simple.html Outdated Show resolved Hide resolved

formatc1702 force-pushed the feature/technical-drw branch from a8731e2 to 83ab27a Compare September 28, 2021 18:54

formatc1702 commented Sep 28, 2021

View reviewed changes