Merge pull request #48 from dangunter/docs_rework1

Rework UI docs
IDAES · Apr 3, 2024 · bbe6e43 · bbe6e43
2 parents 64aa624 + e01d8b7
commit bbe6e43
Show file tree

Hide file tree

Showing 62 changed files with 6,903 additions and 290 deletions.
diff --git a/.github/workflows/core.yml b/.github/workflows/core.yml
@@ -123,4 +123,10 @@ jobs:
         with:
           wait-on-timeout: 20
           command: npm run test
-          browser: chrome
+          browser: chrome
+      - name: Upload screenshots
+        if: ${{ always() }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: cypress-screenshots-${{ matrix.install-variant }}-py${{ matrix.python-version }}-${{ matrix.os }}
+          path: cypress/screenshots
diff --git a/...owsheet_main_component/stream_table_component/stream_table_header/stream_table_header.tsx b/...owsheet_main_component/stream_table_component/stream_table_header/stream_table_header.tsx
@@ -34,7 +34,7 @@ export default function StreamTableHeader(){
             </ul>
           </div>
           <span 
-            id="minimize-flowsheet-panel-btn"
+            id="minimize-streamtable-panel-btn"
             className={`pd-sm ${css.flowsheet_header_icon_container} 
             ${css.flowsheetHeader_small_icon}`}
             onClick={()=>minimizePanel('streamTable', setPanelState)}

diff --git a/docs/README.txt b/docs/README.txt
@@ -0,0 +1,4 @@
+README for IDAES-UI docs
+=========================
+
+
diff --git a/docs/_static/fv/fv-arch.png b/docs/_static/fv/fv-arch.png
diff --git a/docs/_static/fv/fv-basic-flow.png b/docs/_static/fv/fv-basic-flow.png
diff --git a/docs/_static/fv/fv1.png b/docs/_static/fv/fv1.png
diff --git a/docs/_static/fv/fv2.png b/docs/_static/fv/fv2.png
diff --git a/docs/_static/fv/fv3.png b/docs/_static/fv/fv3.png
diff --git a/docs/_static/fv/fvb1.png b/docs/_static/fv/fvb1.png
diff --git a/docs/_static/fv/fvg1.png b/docs/_static/fv/fvg1.png
diff --git a/docs/_static/fv/fvr1.png b/docs/_static/fv/fvr1.png
diff --git a/docs/_static/fv/fvr2.png b/docs/_static/fv/fvr2.png
diff --git a/docs/_static/fv/fvr3.png b/docs/_static/fv/fvr3.png
diff --git a/docs/_static/fv/fvr4.png b/docs/_static/fv/fvr4.png
diff --git a/docs/_static/fv/fvst1.png b/docs/_static/fv/fvst1.png
diff --git a/docs/_static/fv/fvst2.png b/docs/_static/fv/fvst2.png
diff --git a/docs/_static/fv/fvst3.png b/docs/_static/fv/fvst3.png
diff --git a/docs/_static/sample_fv.png b/docs/_static/sample_fv.png
diff --git a/docs/collab.md b/docs/collab.md
@@ -0,0 +1,22 @@
+# Collaborating institutions
+
+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}
+
+## 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}
+
+## Sponsor
+
+This work was sponsored by the Department of Energy, Fossil Energy and Carbon Management
+
+![DOE logo](/static/institution_logos/doe.jpg){w=400px}
diff --git a/docs/conf.py b/docs/conf.py
@@ -20,11 +20,12 @@
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 # HTML
+static_dir = "static"
 html_theme = "sphinx_book_theme"
-html_static_path = ["_static"]
-html_logo = "_static/logo.png"
+html_static_path = [static_dir]
+html_logo = "static/logo.png"
 html_theme_options = {
-    "logo": {"image_light": "_static/logo.png", "image_dark": "_static/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,
@@ -35,7 +36,14 @@
 myst_heading_anchors = 3
 myst_enable_extensions = [
     "deflist",  # definition lists
+    "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",
+}
 
 # Autodoc
 autosummary_generate = True

diff --git a/docs/contacts.md b/docs/contacts.md
@@ -0,0 +1,18 @@
+# Contacts and Links
+
+The IDAES UIs are part of the IDAES Integrated Platform, so links and contacts for that platform are all relevant to the UI:
+
+**Q&A**
+* Main IDAES support mailing list: [[email protected]](mailto:[email protected])
+* [IDAES project web page](https://idaes.org/)
+* [GitHub Discussion page](https://github.com/IDAES/idaes-pse/discussions)
+* [UI-specific discussions on GitHub](https://github.com/IDAES/idaes-pse/discussions/1367)
+
+**Documentation**
+* [IDAES main documentation](https://idaes-pse.readthedocs.io/en/stable/)
+* [IDAES UI documentation](https://idaes-ui.readthedocs.io/) (includes this page)
+
+**GitHub repositories**
+* [IDAES-UI](https://github.com/IDAES/idaes-ui) - User interfaces
+* [IDAES-PSE](https://github.com/IDAES/idaes-pse) - Modeling libraries, core and apps
+* [Examples](https://github.com/IDAES/examples)
diff --git a/docs/design.md → docs/developer/fv.md b/docs/design.md → docs/developer/fv.md
@@ -1,7 +1,11 @@
-# Design
+# {{ vistitle }} for Developers
 
-Currently there is one IDAES UI, the Flowsheet Visualizer (FV).
-The architecture and design of the FV uses a pattern that is shared
+**TODO** 
+* Overall design diagram
+* How to make changes
+
+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
 based on the IDAES Integrated Platform (IDAES-IP), e.g. WaterTAP and PARETO.
 The basics of this design are illustrated below.
@@ -10,6 +14,3 @@ run on the desktop by an individual user or as a service across users.
 A secondary goal is to build a common set of front-end and 
 back-end UI support libraries that can unify and accelerate application
 development across the IDAES-IP.
-
-![IDAES Web Application Architecture diagram](_static/fv/fv-arch.png)
-
diff --git a/docs/developer/index.md b/docs/developer/index.md
@@ -0,0 +1,10 @@
+(developer-documentation)=
+# Developer Documentation
+
+```{toctree}
+---
+hidden: true
+---
+install
+fv
+```
diff --git a/docs/install.md → docs/developer/install.md b/docs/install.md → docs/developer/install.md
@@ -1,27 +1,13 @@
-# Installation
+# Developer Installation
 
-Below are installation instructions for installing IDAES UIs.
-More details on overall IDAES installation and usage 
-are on the [IDAES documentation](https://idaes-pse.readthedocs.io/en/stable/) site.
-
-## User installation
-
-If you want to use the UIs (not develop new code),
-then use `pip` to install the software as part of the 
-IDAES Integrated Platform (IDAES-IP).
-
-```shell
-pip install "idaes-pse[ui]"
-```
-
-## Developer installation
+## Install
 
 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`
 
-### Building the docs
+## Building the docs
 
 For developers, to build this documentation locally:
 

diff --git a/docs/fv-view_fs_tb.png b/docs/fv-view_fs_tb.png
diff --git a/docs/fv.md b/docs/fv.md
diff --git a/docs/index.md b/docs/index.md
@@ -1,20 +1,25 @@
 # IDAES User Interface Documentation
 
 This documentation describes user interfaces (UIs) for the
-<a href="https://idaes.org" target="_blank">Institute for Design of Advanced Energy Systems (IDAES)</a>
-Integrated Platform, which are distributed through the [idaes-pse](https://pypi.org/project/idaes-pse/)
-package on PyPI.
+Institute for Design of Advanced Energy Systems (IDAES)
+Integrated Platform.
+
+This documentation is divided into two main sections:
+
+[User Documentation](#user-documentation)
+: For those who wish to use the UIs, including IDAES and other model developers who are using, e.g., the {{ vistitle }} UI for debugging.
+
+[Developer Documentation](#developer-documentation)
+: For those who wish to change, add to, or extend the IDAES UIs by changing the UI code itself.
 
 ```{toctree}
 ---
-maxdepth: 1
+hidden: true
 ---
-install.md
-fv.md
-design.md
+user/index
+developer/index
+collab
+contacts
 ```
 
-<img src="_static/fv/fv-basic-flow.png" width="75%"></img>
-
-*Diagram showing the basic workflow for model developers using the IDAES visualization tools*
-
+Links and contact information for both users and developers are on the [Contacts](#contacts) page.
diff --git a/docs/pytest.ini b/docs/pytest.ini
@@ -0,0 +1,8 @@
+[pytest]
+minversion = 8.0
+addopts = -q --disable-warnings --strict
+testpaths =
+    tests
+markers =
+    unit
+    screenshot