Merge pull request #53 from CopyDemon/idaes-doc-update

Update IDAES UI documentation
IDAES · Sep 13, 2024 · 06b513b · 06b513b
2 parents e21d56e + fa16b2b
commit 06b513b
Show file tree

Hide file tree

Showing 37 changed files with 427 additions and 80 deletions.
diff --git a/docs/collab.md b/docs/collab.md
@@ -3,20 +3,13 @@
 IDAES is a collaboration between several national laboratories and universities:
 
 ## National Laboratories
-
-![NETL](/static/institution_logos/netl.png){w=200px}
-![LBNL](/static/institution_logos/lbnl.jpg){w=200px}
-![SNL](/static/institution_logos/snl.png){w=200px}
+![National Laboratories](/static/institution_logos/national-lab-logo.png){w="100%"}
 
 ## Universities
-
-![CMU](/static/institution_logos/cmu.png){w=200px}
-![UND](/static/institution_logos/und.png){w=200px}
-![WVU](/static/institution_logos/wvu.png){w=200px}
-![GATech](/static/institution_logos/gatech.png){w=200px}
+![Universities](/static/institution_logos/universities-logo.png){w="100%"}
 
 ## Sponsor
 
 This work was sponsored by the Department of Energy, Fossil Energy and Carbon Management
 
-![DOE logo](/static/institution_logos/doe.jpg){w=400px}
+![DOE logo](/static/institution_logos/DOE-logo.png){w="100%"}
diff --git a/docs/conf.py b/docs/conf.py
@@ -15,34 +15,41 @@
     "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
+    "sphinxcontrib.video",
 ]
 templates_path = ["_templates"]
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".pytest_cache"]
 
 # HTML
 static_dir = "static"
 html_theme = "sphinx_book_theme"
 html_static_path = [static_dir]
 html_logo = "static/logo.png"
 html_theme_options = {
-    "logo": {"image_light": f"{static_dir}/logo.png", "image_dark": f"{static_dir}/logo.png"},
+    "logo": {
+        "image_light": f"{static_dir}/logo.png",
+        "image_dark": f"{static_dir}/logo.png",
+    },
     "repository_provider": "github",
     "repository_url": "https://github.com/IDAES/idaes-ui",
     "use_repository_button": True,
     "path_to_docs": "docs",
 }
 
 # MyST
-myst_heading_anchors = 3
+myst_heading_anchors = 6
 myst_enable_extensions = [
     "deflist",  # definition lists
-    "attrs_inline", # inline attributes on images using MD syntax
-    "substitution", # for global substitutions; see myst_substitutions
+    "attrs_inline",  # inline attributes on images using MD syntax
+    "substitution",  # for global substitutions; see myst_substitutions
 ]
 myst_substitutions = {
     # Change these two lines to rename the Flowsheet Visualizer (!)
     "vistitle": "Flowsheet Visualizer",
     "visabbr": "FV",
+    "mov": "mov",
+    "mp4": "mp4",
+    "video-width": 800,
 }
 
 # Autodoc

diff --git a/docs/developer/fv.md b/docs/developer/fv.md
@@ -1,9 +1,57 @@
 # {{ vistitle }} for Developers
 
-**TODO** 
-* Overall design diagram
-* How to make changes
+## Start {{ visabbr }} example
+After installation you can start to run the flowsheet visualizer example by run:
 
+```python
+python -m idaes_ui.fv.example
+```
+
+If you have Node.js 18 installed you can also run:
+```bash
+npm run ui
+```
+
+## Code structure
+### Python part:
+The Python code is responsible for backend tasks, such as starting the HTTP server, converting the flowsheet model to a JSON file, etc.
+
+All files related to the FV on the Python side are located in `repo_root/idaes_ui/fv/`
+
+Includes: 
+1. FV visualizer
+1. FV backend server
+1. FV flowsheet
+1. FV diagnostics
+1. FV settings
+1. FV example
+1. FV test
+
+### UI part
+The JS code is responsible for frontend tasks and handles browser-side UI rendering. It uses React and Node.js to generate a modern single-page application.
+
+All UI files are loaded in `repo_root/IDAES-UI/`
+
+---
+
+## How to make changes
+
+### Make change in backend
+You can start {{ visabbr }} with `pip install -e .` ,  Once {{ visabbr }} successfully started, you can make direct changes to the code and save to apply your changes.
+
+### Make change in frontend
+1. Navigate to `repo_root/IDAES-UI/`
+2. Make sure you have `Node.js 18` installed, and then run `npm install`
+3. Run `vite run dev` command to start the frontend development server in the browser.
+
+Attention:  
+The frontend UI development environment requires the Python backend server to be started and running, or the API calls will fail, and the diagram will not display in the browser.
+
+### Build React
+The changes you make in the `IDAES-UI` folder are only for the development environment. To apply your changes to FV, you need to run the `npm run build` command.
+
+
+## Learn more about IDAES UI:
 Currently there is one IDAES UI, the {{ vistitle }} ({{ visabbr }}).
 The architecture and design of the {{ visabbr }} uses a pattern that is shared
 across other UIs in other Advanced Process Systems Engineering applications

diff --git a/docs/developer/index.md b/docs/developer/index.md
@@ -1,6 +1,14 @@
 (developer-documentation)=
 # Developer Documentation
 
+If you wish to only use IDAES UI, please see [User documentation section](user-documentation).
+
+---
+## Quick links:
+
+* [Developer Installation](installation)
+* [{{vistitle}} for Developers](fv_main_page)
+
 ```{toctree}
 ---
 hidden: true

diff --git a/docs/developer/install.md b/docs/developer/install.md
@@ -1,11 +1,25 @@
 # Developer Installation
 
-## Install
+## Before installation:
+
+1. The Flowsheet Visualizer UI supports `Python >= 3.8`
+1. The Flowsheet Visualizer UI needs `Node.js 18`
+1. For best practices, you can create a separate Python environment and install it there
+
+## Installation
 
 If you want to install for development
 
-1) Clone the [GitHub repository](https://github.com/IDAES/idaes-ui)
-2) From the root of the cloned repo run: `pip install -r requirements-dev.txt`
+1. Clone the [GitHub repository](https://github.com/IDAES/idaes-ui)
+1. Install python code and python dependency
+    1. From the root of the cloned repo run:  
+    `pip install -e .`  
+    `pip install -r requirements-dev.txt`
+1. Install Node.js dependency (Optional)
+    1. For install testing dependency from the root of the cloned repo run:  
+    `npm install`
+    2. For install React dependency Navigate to IDAES-UI folder and run:  
+    `npm install`
 
 ## Building the docs
 

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,3 +1,4 @@
 sphinx
 sphinx-book-theme
 myst-parser
+sphinxcontrib-video
diff --git a/docs/static/fv/fv-diagnostics-panel-overview.png b/docs/static/fv/fv-diagnostics-panel-overview.png
diff --git a/docs/static/fv/fv-diagram-panel.png b/docs/static/fv/fv-diagram-panel.png
diff --git a/docs/static/fv/fv-header-flowsheet-name.png b/docs/static/fv/fv-header-flowsheet-name.png
diff --git a/docs/static/fv/fv-header.png b/docs/static/fv/fv-header.png
diff --git a/docs/static/fv/fv-overview-diagnostic-open.png b/docs/static/fv/fv-overview-diagnostic-open.png
diff --git a/docs/static/fv/fv-stream-table-overview.png b/docs/static/fv/fv-stream-table-overview.png
diff --git a/docs/static/fv/fv-view_di.png b/docs/static/fv/fv-view_di.png
diff --git a/docs/static/fv/fv-view_fs_tb.png b/docs/static/fv/fv-view_fs_tb.png
diff --git a/docs/static/fv/videos/fv-diagnostics-next-steps-open-in-jupyter.mp4 b/docs/static/fv/videos/fv-diagnostics-next-steps-open-in-jupyter.mp4
diff --git a/docs/static/fv/videos/fv-diagnostics-run-suggested-next-step.mp4 b/docs/static/fv/videos/fv-diagnostics-run-suggested-next-step.mp4
diff --git a/docs/static/fv/videos/fv-download-diagram.mp4 b/docs/static/fv/videos/fv-download-diagram.mp4
diff --git a/docs/static/fv/videos/fv-multiple-selection.mp4 b/docs/static/fv/videos/fv-multiple-selection.mp4
diff --git a/docs/static/fv/videos/fv-overview-resize-drag-panel.mp4 b/docs/static/fv/videos/fv-overview-resize-drag-panel.mp4
diff --git a/docs/static/fv/videos/fv-reset-layout.mp4 b/docs/static/fv/videos/fv-reset-layout.mp4
diff --git a/docs/static/fv/videos/fv-rotate-component.mp4 b/docs/static/fv/videos/fv-rotate-component.mp4
diff --git a/docs/static/fv/videos/fv-stream-table-hide-column.mp4 b/docs/static/fv/videos/fv-stream-table-hide-column.mp4
diff --git a/docs/static/fv/videos/fv-stream-table-reorder.mp4 b/docs/static/fv/videos/fv-stream-table-reorder.mp4
diff --git a/docs/static/fv/videos/fv-toggle-diagnostics-panel.mp4 b/docs/static/fv/videos/fv-toggle-diagnostics-panel.mp4
diff --git a/docs/static/fv/videos/fv-toggle-stream-labels.mp4 b/docs/static/fv/videos/fv-toggle-stream-labels.mp4
diff --git a/docs/static/fv/videos/fv-zoom-to-fit.mp4 b/docs/static/fv/videos/fv-zoom-to-fit.mp4
diff --git a/docs/static/fv/videos/fv-zoom.mp4 b/docs/static/fv/videos/fv-zoom.mp4
diff --git a/docs/static/fv/zoom-in-out.mp4 b/docs/static/fv/zoom-in-out.mp4
diff --git a/docs/static/institution_logos/DOE-logo.png b/docs/static/institution_logos/DOE-logo.png
diff --git a/docs/static/institution_logos/national-lab-logo.png b/docs/static/institution_logos/national-lab-logo.png
diff --git a/docs/static/institution_logos/universities-logo.png b/docs/static/institution_logos/universities-logo.png
diff --git a/docs/user/fv/concepts.md b/docs/user/fv/concepts.md
@@ -3,11 +3,14 @@
 
 ## Overview
 
-The {{ vistitle }} ({{ visabbr }}) is intended for exploring existing IDAES models.
+The {{ vistitle }} ({{ visabbr }}) is intended for exploring existing IDAES models. </br>
 It will automatically generate a diagram for any model.
-Here is an example of the default display:
 
-![default](/static/fv/fv-view_fs_tb.png){w="80%"}
+---
+
+**Here is an example of the default display:**
+
+![default](/static/fv/fv-view_fs_tb.png){w="100%"}
 
 You can see here the diagram and stream table.
 
@@ -21,10 +24,14 @@ You can see here the diagram and stream table.
 
 Currently, the {{ visabbr }} is designed to be run locally, on a user's desktop machine.
 Although the interface shows in a web browser, it will be getting its information from the local memory where the model was created and solved.
+
 Because the {{ visabbr }} stays in communication with the Python interpreter that started it, 
 if you are running in an interactive Python interpreter -- including a Python console, Jupyter Notebook, or IDE window -- then any subsequent changes to the underlying model (structural or by re-solving) can be reflected in the {{ visabbr }}.
+
 As a corollary, {{ visabbr }} exits with the Python interpreter, so if you are running a script that invokes the {{ visabbr }} at the end to view the results, make sure you don't exit the program; see the [run from a script](#fv-run-script) in the How-to for more details.
 
-A summary of the interactive workflow that the {{ visabbr }} enables is shown below:
+---
+
+## Summary of the interactive workflow:
 
 ![flow](/static/fv/workflow.png){w="80%" background="transparent"}