Merge pull request #60 from CopyDemon/issue-59-update-documentation-h…

…ow-to-use-send-back-diagram-image

Issue 59 update documentation how to use send back diagram image

docs/README.md

@@ -0,0 +1,21 @@
+README for IDAES-UI docs
+=========================
+
+
+### Merge and build
+* When merging changes to IDAES-UI, the CI will automatically run and build the documentation to the online server.
+
+### Run as developer
+```bash
+# Change to the docs directory
+
+# Install the required packages
+pip install -r requirements.txt
+
+# Install sphinx-autobuild
+# This is necessary for building a local development server to view live changes.
+pip install sphinx-autobuild
+
+# Run the live server using Sphinx-autobuild.
+sphinx-autobuild . _build/html
+```

docs/user/fv/index.md

@@ -12,6 +12,7 @@ tasks with the {{ visabbr }}.
 
 * [Flowsheet Visualizer Concepts](fv-concepts)
 * [Flowsheet Visualizer How-to](fv-howto)
+* [Save and Preview Diagram](save-preview-diagram)
 
 ```{toctree}
 :hidden: true

docs/user/index.md

@@ -11,11 +11,13 @@ If you wish to develop or extend IDAES UIs, please also see the [developer docum
 
 * [Installation](installation)
 * [{{vistitle}}](fv_main_page)
+* [Save and Preview Diagram](save_diagram)
 
 ```{toctree}
 ---
 hidden: true
 ---
 install
 fv/index
+save-diagram/index
 ```

docs/user/save-diagram/index.md

@@ -0,0 +1,44 @@
+(save-preview-diagram)=
+# Save and Preview Flowsheet Diagram  
+
+### Overview:  
+IDAES UI allows you to preview your flowsheet diagram at any time while working on it by calling `export_flowsheet_diagram`.
+
+### Usage:
+The export_flowsheet_diagram function is used to return the current view of the flowsheet diagram at any time after you have initialized your model.
+* It can save the diagram to your preferred path or the default path.
+* It can display the current view of the flowsheet diagram in a Jupyter Notebook.
+
+### Parameters:
+`export_flowsheet_diagram` takes three parameters:
+* `flowsheet`: The flowsheet object
+* `name`: The diagram filename or full path where you prefer to save the diagram. The output format is determined by the file extension (".svg" for SVG and ".png" for PNG).
+* `display`: Boolean, to determent if you want to review current flowsheet in jupyter notebook
+
+#### Let's go over it step by step.
+1. Import `export_flowsheet_diagram` function from `idaes_ui` package
+    ```python
+    from idaes_ui.fv.fsvis import export_flowsheet_diagram
+    ```
+2. Create your model. Here we assume the model is called `m` and
+   the top-level flowsheet that you want to view is `m.fs`.
+
+3. After initializing your model, you should have `m.fs`.   
+Then, you can call `export_flowsheet_diagram`.
+    ```python
+    export_flowsheet_diagram(m.fs, '~/Download/my_flowsheet_diagram.svg', display=True)
+    ```
+
+4. Then, you can see the flowsheet diagram's saved path in the log.
+
+### View flowsheet diagram
+1. To view the image, after calling `export_flowsheet_diagram`, you can visit the path shown in the log.
+2. To view the flowsheet diagram in a Jupyter Notebook, set `display=True`. This will automatically display the flowsheet diagram in the notebook.
+
+### Demo
+```{video} /static/save_diagram/videos/demo_video_export_flowsheet_diagram.mp4
+:width: 800
+:nocontrols:
+:autoplay: true
+:loop:
+```

idaes_ui/fv/fsvis.py

@@ -269,7 +269,9 @@ def _init_logging(lvl):
     ui_logger.setLevel(lvl)
 
 
-def export_flowsheet_diagram(flowsheet, name: Union[str, Path]) -> Path:
+def export_flowsheet_diagram(
+    flowsheet, name: Union[str, Path], display: bool = False
+) -> Path:
     """Export the flowsheet as a diagram.
 
     Some example invocations (flowsheet is in `m.fs`)::
@@ -322,13 +324,13 @@ def export_flowsheet_diagram(flowsheet, name: Union[str, Path]) -> Path:
     try:
         d.mkdir(parents=True, exist_ok=True)
     except Exception as err:
-        raise IOError(f"Cannot make directory {d}: {err}")
+        raise IOError(f"Cannot make directory {d}: {err}") from err
     if imtype not in ("svg", "png"):
         raise ValueError(f"File extension must be '.svg' or '.png' (got: '.{imtype}')")
     r = visualize(flowsheet, basename, browser=False).save_diagram(
         screenshot_name=basename,
         screenshot_save_to=str(d),
         image_type=imtype,
-        display=False,
+        display=display,
     )
     return Path(r["diagram_saved_path"])