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.