Conversation
There was a problem hiding this comment.
Pull request overview
Adds documentation strings into the EDG IR via a _docs metadata entry and plumbs that information into the compiled design export models so block/port/param docs can be surfaced in JSON.
Changes:
- Populate
_docsmetadata on blocks during proto generation (block docstring + per-param/per-port docs). - Extend compiled design export models to include
docfields and populate them from_docs. - Add unit tests validating
_docsmetadata generation and compiled export doc propagation.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| edg/core/Blocks.py | Adds _add_doc_metadata() and injects _docs into block metadata during proto generation. |
| edg/core/CompiledDesignExport.py | Adds doc fields to exported models and populates docs from block metadata; updates JSON postprocessing. |
| edg/core/test_block.py | Adds docstrings/docs to a test block and asserts _docs metadata contents in the generated proto. |
| edg/core/test_common.py | Adds docstrings and port docs to common test blocks used by other export tests. |
| edg/core/test_compiled_design_export.py | Asserts exported CompiledBlock.doc and CompiledPort.doc values in hierarchy export test. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
18
to
36
| class CompiledParam(BaseModel): | ||
| # this is minimalistic so the output json is more compact | ||
| type: str | ||
| value: Optional[Any] # solved value, if available | ||
| doc: Optional[str] # doc specified by its parent block, if available | ||
|
|
||
|
|
||
| class CompiledPortArray(RootModel[Dict[str, Union["CompiledPort", "CompiledPortArray"]]]): | ||
| pass | ||
|
|
||
|
|
||
| class CompiledPort(BaseModel): | ||
| path: PathType # provide the full path to allow searchability | ||
| cls: str # self class | ||
| # path of connected port, if connected | ||
| # for block ports, this is the link, if connected to one | ||
| connected_path: Optional[Union[PathType, List[PathType]]] | ||
| doc: Optional[str] # doc specified by its parent block, if available | ||
| # note, link ports do not have parameters (they inherit parameters from connected ports and are deduplicated here) |
Comment on lines
+151
to
+155
| for port_name, port_value in ports_dict.items(): | ||
| if port_name in meta_docs.members.node and isinstance(port_value, CompiledPort): | ||
| port_doc = meta_docs.members.node.get(port_name) | ||
| if port_doc is not None: | ||
| port_value.doc = port_doc.text_leaf |
Comment on lines
+351
to
+352
| if self.__doc__: | ||
| metadata_dict[""] = inspect.cleandoc(self.__doc__) |
Comment on lines
+26
to
+28
| class CompiledPortArray(BaseModel): | ||
| doc: Optional[str] = None # doc specified by its parent block, if available | ||
| elts: Dict[str, Union["CompiledPort", "CompiledPortArray"]] |
Comment on lines
67
to
+70
| compiled_json_file.write( | ||
| CompiledDesignExportTransform.postprocess_serialized_json(compiled_json.model_dump_json(indent=2)) | ||
| CompiledDesignExportTransform.postprocess_serialized_json( | ||
| compiled_json.model_dump_json(indent=2, exclude_none=True) | ||
| ) |
Comment on lines
+350
to
+353
| metadata_dict: Dict[str, str] = {} | ||
| if self.__doc__: | ||
| metadata_dict[""] = inspect.cleandoc(self.__doc__) | ||
| for name, param in self._parameters.items(): |
| for name, port in self._ports.items(): | ||
| if port in self._port_docs: | ||
| metadata_dict[name] = self._port_docs[port] | ||
| self._docs = self.Metadata(metadata_dict) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Structurally, this adds docs as a metadata field. indexed by the port or param name, with the block docstring itself being the empty string as the root.
For json export, this only applies to blocks, not links.
This changes the export format for port-arrays to allow a doc field. This also excludes all None (null) values from the export to reduce clutter but provides a default for importability.