DMF Help

The DMF help function provides a link between objects that the user is working with in a Jupyter Notebook and the detailed documentation pages that you have created for those objects in Sphinx.

Creating help pages

The mechanism is relatively simple, once you have a documentation page already created. Simply add special “index” entries at the appropriate place in the page, with the following format:

.. index::
    pair: full.path.to.your.module;ClassName

For example, if you were to add help for the Port class of the idaes.core.ports, you could add the following to the page:

.. index::
    pair: idaes.core.ports;Port

You can have multiple index entries for the same page.

DMF Help Configuration

The DMF finds the help pages by searching a user-configured set of paths that point to the generated (note: not the source) HTML documentation. This information goes under the htmldocs keyword in the DMF configuration file (found in <workspace_root>/config.yaml).

Using the special key {dmf_root} to indicate the root of the DMF installation, the default configuration is:

htmldocs:
- '{dmf_root}/doc/build/html/dmf'
- '{dmf_root}/doc/build/html/models'

Sensible values for these documentation paths are automatically generated by the dmf init command, and most users will not need to modify this. Note that these paths are searched in the order given, and the first match is the one used.

DMF Help Usage

In the Jupyter notebook, the %dmf help <object-or-class> magic will invoke the help functionality. If a page is found, it will be automatically shown in a new window or tab of the browser. See this Jupyter notebook for an example of using the %dmf help magics.