Intersphinx config, script, and example

idaes_examples/notebooks/_config.yml

@@ -13,8 +13,20 @@ sphinx:
   config:
     bibtex_reference_style: author_year
     exclude_patterns: ['**/.jupyter_cache']
-title: IDAES Examples
-repository:
+    intersphinx_mapping:
+      idaes:
+      - https://idaes-pse.readthedocs.io/en/stable/
+      - null
+      idaes-examples:
+      - https://idaes-examples.readthedocs.io/en/stable/
+      - null
+      prommis:
+      - https://prommis.readthedocs.io/en/stable/
+      - null
+      watertap:
+      - https://watertap.readthedocs.io/en/stable/
+      - null
+
   # `path_to_book` should point to the directory containing this file (`_config.yml`)
   path_to_book: idaes_examples/notebooks
   # FIXME change `url` and `branch` before merging PR

idaes_examples/notebooks/docs/diagnostics/diagnostics_toolbox.ipynb

@@ -40,7 +40,7 @@
     "\n",
     "Model diagnosis and debugging is often more of an art than a science, and it generally relies on significant experience and understanding both of general EO modeling techniques and the specific model and problem being solved. To assist with this process, IDAES has developed a model diagnostics toolbox that brings together a large number of tools for identifying potential issues in a model to help guide the user through the process of finding and resolving these issues. Note however that whilst these tools can help identify the presence of an issue, remedying the issue always requires some degree of engineering knowledge about the system being modeled, and thus it is ultimately up to the user to find a solution to the problem.\n",
     "\n",
-    "This tutorial will take you through using the ``DiagnosticsToolbox`` to debug a number of issues in a simple Pyomo model and to take it from initially reporting a possible infeasible solution to returning the correct solution.\n",
+    "This tutorial will take you through using the {py:class}`DiagnosticsToolbox <idaes.core.util.model_diagnostics.DiagnosticsToolbox>` to debug a number of issues in a simple Pyomo model and to take it from initially reporting a possible infeasible solution to returning the correct solution.\n",
     "\n",
     "To get started, the ``DiagnosticsToolbox`` can be imported from ``idaes.core.util``.\n",
     "\n",

idaes_examples/notebooks/docs/diagnostics/diagnostics_toolbox_exercise.ipynb

@@ -38,7 +38,7 @@
         "\n",
         "Model diagnosis and debugging is often more of an art than a science, and it generally relies on significant experience and understanding both of general EO modeling techniques and the specific model and problem being solved. To assist with this process, IDAES has developed a model diagnostics toolbox that brings together a large number of tools for identifying potential issues in a model to help guide the user through the process of finding and resolving these issues. Note however that whilst these tools can help identify the presence of an issue, remedying the issue always requires some degree of engineering knowledge about the system being modeled, and thus it is ultimately up to the user to find a solution to the problem.\n",
         "\n",
-        "This tutorial will take you through using the ``DiagnosticsToolbox`` to debug a number of issues in a simple Pyomo model and to take it from initially reporting a possible infeasible solution to returning the correct solution.\n",
+        "This tutorial will take you through using the {py:class}`DiagnosticsToolbox <idaes.core.util.model_diagnostics.DiagnosticsToolbox>` to debug a number of issues in a simple Pyomo model and to take it from initially reporting a possible infeasible solution to returning the correct solution.\n",
         "\n",
         "To get started, the ``DiagnosticsToolbox`` can be imported from ``idaes.core.util``.\n",
         "\n",
@@ -783,4 +783,4 @@
   },
   "nbformat": 4,
   "nbformat_minor": 3
-}
+}

idaes_examples/notebooks/docs/diagnostics/diagnostics_toolbox_solution.ipynb

@@ -38,7 +38,7 @@
         "\n",
         "Model diagnosis and debugging is often more of an art than a science, and it generally relies on significant experience and understanding both of general EO modeling techniques and the specific model and problem being solved. To assist with this process, IDAES has developed a model diagnostics toolbox that brings together a large number of tools for identifying potential issues in a model to help guide the user through the process of finding and resolving these issues. Note however that whilst these tools can help identify the presence of an issue, remedying the issue always requires some degree of engineering knowledge about the system being modeled, and thus it is ultimately up to the user to find a solution to the problem.\n",
         "\n",
-        "This tutorial will take you through using the ``DiagnosticsToolbox`` to debug a number of issues in a simple Pyomo model and to take it from initially reporting a possible infeasible solution to returning the correct solution.\n",
+        "This tutorial will take you through using the {py:class}`DiagnosticsToolbox <idaes.core.util.model_diagnostics.DiagnosticsToolbox>` to debug a number of issues in a simple Pyomo model and to take it from initially reporting a possible infeasible solution to returning the correct solution.\n",
         "\n",
         "To get started, the ``DiagnosticsToolbox`` can be imported from ``idaes.core.util``.\n",
         "\n",
@@ -2101,4 +2101,4 @@
   },
   "nbformat": 4,
   "nbformat_minor": 3
-}
+}

idaes_examples/notebooks/docs/diagnostics/diagnostics_toolbox_test.ipynb

@@ -38,7 +38,7 @@
         "\n",
         "Model diagnosis and debugging is often more of an art than a science, and it generally relies on significant experience and understanding both of general EO modeling techniques and the specific model and problem being solved. To assist with this process, IDAES has developed a model diagnostics toolbox that brings together a large number of tools for identifying potential issues in a model to help guide the user through the process of finding and resolving these issues. Note however that whilst these tools can help identify the presence of an issue, remedying the issue always requires some degree of engineering knowledge about the system being modeled, and thus it is ultimately up to the user to find a solution to the problem.\n",
         "\n",
-        "This tutorial will take you through using the ``DiagnosticsToolbox`` to debug a number of issues in a simple Pyomo model and to take it from initially reporting a possible infeasible solution to returning the correct solution.\n",
+        "This tutorial will take you through using the {py:class}`DiagnosticsToolbox <idaes.core.util.model_diagnostics.DiagnosticsToolbox>` to debug a number of issues in a simple Pyomo model and to take it from initially reporting a possible infeasible solution to returning the correct solution.\n",
         "\n",
         "To get started, the ``DiagnosticsToolbox`` can be imported from ``idaes.core.util``.\n",
         "\n",
@@ -1862,4 +1862,4 @@
   },
   "nbformat": 4,
   "nbformat_minor": 3
-}
+}

idaes_examples/notebooks/docs/diagnostics/diagnostics_toolbox_usr.ipynb

@@ -38,7 +38,7 @@
         "\n",
         "Model diagnosis and debugging is often more of an art than a science, and it generally relies on significant experience and understanding both of general EO modeling techniques and the specific model and problem being solved. To assist with this process, IDAES has developed a model diagnostics toolbox that brings together a large number of tools for identifying potential issues in a model to help guide the user through the process of finding and resolving these issues. Note however that whilst these tools can help identify the presence of an issue, remedying the issue always requires some degree of engineering knowledge about the system being modeled, and thus it is ultimately up to the user to find a solution to the problem.\n",
         "\n",
-        "This tutorial will take you through using the ``DiagnosticsToolbox`` to debug a number of issues in a simple Pyomo model and to take it from initially reporting a possible infeasible solution to returning the correct solution.\n",
+        "This tutorial will take you through using the {py:class}`DiagnosticsToolbox <idaes.core.util.model_diagnostics.DiagnosticsToolbox>` to debug a number of issues in a simple Pyomo model and to take it from initially reporting a possible infeasible solution to returning the correct solution.\n",
         "\n",
         "To get started, the ``DiagnosticsToolbox`` can be imported from ``idaes.core.util``.\n",
         "\n",
@@ -2101,4 +2101,4 @@
   },
   "nbformat": 4,
   "nbformat_minor": 3
-}
+}

scripts/update_intersphinx_mapping.py

@@ -0,0 +1,84 @@
+"""
+Update the intersphinx_mapping value in conf.py
+
+You should run this after you run `jupyterbook config sphinx`.
+"""
+__author__ = "Dan Gunter (LBNL)"
+
+import argparse
+from pathlib import Path
+import sys
+from tempfile import TemporaryFile
+import yaml
+from idaes.core.util.intersphinx import get_intersphinx_mapping
+
+CONF_FILE = "_config.yml"
+
+
+def indent_length(line):
+    i = 0
+    while line[i] == " ":
+        i += 1
+    return i
+
+
+def create_modified_file(path):
+    ix_indent, in_ix = 0, False
+    # get the mapping to insert
+    mapping = get_intersphinx_mapping()
+    # change tuples to lists so yaml.dump doesn't do weird things
+    for key in mapping:
+        mapping[key] = list(mapping[key])
+    yaml_text = yaml.dump({"intersphinx_mapping": mapping})
+    # Create temporary file with new mapping in it by
+    # replacing all lines under 'intersphinx_mapping: ...'
+    # with the new YAML text.
+    tmp = TemporaryFile("w+")
+    for line in path.open("r"):
+        if in_ix:
+            # Detect end of the block with a return to the same indent
+            if indent_length(line) <= ix_indent:
+                # write out the new YAML mapping
+                indent_spc = " " * ix_indent
+                for new_line in yaml_text.split("\n"):
+                    tmp.write(indent_spc + new_line + "\n")
+                # switch back to 'normal' mode
+                in_ix = False
+            # else: swallow this line
+        elif line.lstrip().startswith("intersphinx_mapping"):
+            # switch to 'in intersphinx_mapping' mode
+            ix_indent, in_ix = indent_length(line), True
+        else:
+            tmp.write(line)
+    return tmp
+
+
+def replace_original_file(tmp_f, path):
+    tmp_f.seek(0)
+    with path.open("w") as f:
+        for line in tmp_f:
+            f.write(line)
+
+
+if __name__ == "__main__":
+    ap = argparse.ArgumentParser()
+    ap.add_argument("-d", "--dir",
+                    help="Directory containing conf.py (default=.)",
+                    default=None)
+    p = ap.parse_args()
+    if p.dir is None:
+        doc_dir = Path(".")
+    else:
+        doc_dir = Path(p.dir)
+
+    conf_file = doc_dir / CONF_FILE
+    if not conf_file.exists():
+        print(f"Config file `{CONF_FILE}` not found in `{doc_dir}`")
+        sys.exit(1)
+
+    tmp_file = create_modified_file(conf_file)
+    replace_original_file(tmp_file, conf_file)
+
+    print(f"Modified configuration file: {conf_file}")
+
+    sys.exit(0)