diff --git a/docs/source/development/guides.rst b/docs/source/development/guides.rst new file mode 100644 index 000000000..eae1225b0 --- /dev/null +++ b/docs/source/development/guides.rst @@ -0,0 +1,51 @@ +.. _develop:guides: + +****** +Guides +****** + +Throughout the app, instances of ``aiidalab_qe.common.infobox.InAppGuide`` have been dropped to provide users with helpful information in the form of toggleable tutorials. +These guide section widgets observe a global instance of ``aiidalab_qe.common.guide_manager.GuideManager`` to obtain their content and toggle their visibility. +The guide manager is initialized at app startup and scans the local codebase, as well as entry-point-based plugins, for defined guides. +The discovered guides are then made available as a nested radio button widget of the form ``category`` -> ``guide``. +This allows both built-in ``general/`` guides and external ``/`` guides, ensuring guide uniqueness. + +Developers have two options when using the ``InAppGuide`` widget: + +#. **Widget-based guide sections**: Developers can define the guide content directly in the widget's constructor using ``ipywidgets`` widgets. + When using this approach, the developer may provide a ``guide_id`` in the constructor to associate the guide section with a specific guide. + Otherwise, if no ``guide_id`` is provided, the guide section will be displayed for any active guide. + + .. code:: python + + InAppGuide( + guide_id="general/basic", + children=[ + ipw.HTML("Some basic information."), + ], + ) + +#. **HTML-based guide sections**: Developers can define the guide content in an HTML document, tagging the various sections using the HTML ``id`` attribute. + The guide manager will load the HTML document associated with the selected guide and parse it using ``BeautifulSoup``. + + .. code:: html + +
+

Some basic information regarding the structure.

+
+ +
+

Some basic information regarding the configuration.

+
+ + ... + + HTML-based ``InAppGuide`` widgets are instantiated without children (or a guide id), but instead with an ``identifier`` corresponding to the relevant HTML ``id`` attribute. + + .. code:: python + + InAppGuide(identifier="structure-step") + +A decent amount of ``InAppGuide(identifier=)`` instances have been placed strategically throughout the app. +Developers may suggest additional core guide sections via GitHub pull requests. +For plugin developers, additional instances of either flavor are recommended to be added in any component of the plugin in conjunction with dedicated plugin-specific guides. diff --git a/docs/source/development/index.rst b/docs/source/development/index.rst index 712b0d37e..c3c37a02a 100644 --- a/docs/source/development/index.rst +++ b/docs/source/development/index.rst @@ -12,3 +12,4 @@ This guide explains the architecture of the application and how to extend the fu architecture plugin plugin_registry + guides diff --git a/src/aiidalab_qe/app/configuration/__init__.py b/src/aiidalab_qe/app/configuration/__init__.py index b9775ea0b..00e549f46 100644 --- a/src/aiidalab_qe/app/configuration/__init__.py +++ b/src/aiidalab_qe/app/configuration/__init__.py @@ -10,6 +10,7 @@ from aiidalab_qe.app.parameters import DEFAULT_PARAMETERS from aiidalab_qe.app.utils import get_entry_items +from aiidalab_qe.common.infobox import InAppGuide from aiidalab_qe.common.panel import ( ConfigurationSettingsModel, ConfigurationSettingsPanel, @@ -114,10 +115,16 @@ def render(self): children=[ ipw.VBox( children=[ + InAppGuide(identifier="properties-selection"), *self.property_children, ] ), - self.tabs, + ipw.VBox( + children=[ + InAppGuide(identifier="calculation-settings"), + self.tabs, + ], + ), ], layout=ipw.Layout(margin="10px 2px"), selected_index=None, @@ -141,6 +148,7 @@ def render(self): self.confirm_button.on_click(self.confirm) self.children = [ + InAppGuide(identifier="configuration-step"), self.structure_set_message, ipw.HTML("""
diff --git a/src/aiidalab_qe/app/configuration/advanced/advanced.py b/src/aiidalab_qe/app/configuration/advanced/advanced.py index 5779d707d..c675b4d83 100644 --- a/src/aiidalab_qe/app/configuration/advanced/advanced.py +++ b/src/aiidalab_qe/app/configuration/advanced/advanced.py @@ -5,6 +5,7 @@ import ipywidgets as ipw +from aiidalab_qe.common.infobox import InAppGuide from aiidalab_qe.common.panel import ConfigurationSettingsPanel from .hubbard import ( @@ -274,11 +275,7 @@ def render(self): self.pseudos.render() self.children = [ - ipw.HTML(""" -
-

Advanced Settings

-
- """), + InAppGuide(identifier="advanced-settings"), ipw.HBox( children=[ self.clean_workdir, diff --git a/src/aiidalab_qe/app/configuration/basic/workflow.py b/src/aiidalab_qe/app/configuration/basic/workflow.py index 4e4147b25..c58084957 100644 --- a/src/aiidalab_qe/app/configuration/basic/workflow.py +++ b/src/aiidalab_qe/app/configuration/basic/workflow.py @@ -6,6 +6,7 @@ import ipywidgets as ipw from aiidalab_qe.app.configuration.basic.model import BasicConfigurationSettingsModel +from aiidalab_qe.common.infobox import InAppGuide from aiidalab_qe.common.panel import ConfigurationSettingsPanel @@ -60,6 +61,7 @@ def render(self): ) self.children = [ + InAppGuide(identifier="basic-settings"), ipw.HTML("""
Below you can indicate both if the material should be treated as an diff --git a/src/aiidalab_qe/app/main.py b/src/aiidalab_qe/app/main.py index 4dbd02f9e..d24bfcbf9 100644 --- a/src/aiidalab_qe/app/main.py +++ b/src/aiidalab_qe/app/main.py @@ -17,6 +17,7 @@ from aiidalab_qe.app.structure.model import StructureStepModel from aiidalab_qe.app.submission import SubmitQeAppWorkChainStep from aiidalab_qe.app.submission.model import SubmissionStepModel +from aiidalab_qe.common.infobox import InAppGuide from aiidalab_qe.common.widgets import LoadingWidget from aiidalab_widgets_base import WizardAppWidget @@ -109,9 +110,12 @@ def __init__(self, qe_auto_setup=True): super().__init__( children=[ + InAppGuide(identifier="guide-warning", classes=["guide-warning"]), self.new_workchain_button, self._process_loading_message, self._wizard_app_widget, + InAppGuide(identifier="post-guide", classes=["post-guide"]), + InAppGuide(children=[ipw.HTML("hello")], guide_id="general/basic"), ] ) diff --git a/src/aiidalab_qe/app/result/__init__.py b/src/aiidalab_qe/app/result/__init__.py index 1f07f1fcc..386f7cd0a 100644 --- a/src/aiidalab_qe/app/result/__init__.py +++ b/src/aiidalab_qe/app/result/__init__.py @@ -3,6 +3,7 @@ from aiida import orm from aiida.engine import ProcessState +from aiidalab_qe.common.infobox import InAppGuide from aiidalab_qe.common.widgets import LoadingWidget from aiidalab_widgets_base import ( ProcessMonitor, @@ -106,6 +107,7 @@ def render(self): ) self.children = [ + InAppGuide(identifier="results-step"), self.process_info, ipw.HBox( children=[ diff --git a/src/aiidalab_qe/app/static/styles/custom.css b/src/aiidalab_qe/app/static/styles/custom.css index 053cf8b92..7cd2171b9 100644 --- a/src/aiidalab_qe/app/static/styles/custom.css +++ b/src/aiidalab_qe/app/static/styles/custom.css @@ -31,13 +31,6 @@ outline: none !important; } -.guide ol { - list-style: none; -} -.guide p:not(:last-of-type) { - margin-bottom: 0.5em; -} - .loading { margin: 0 auto; padding: 5px; diff --git a/src/aiidalab_qe/app/static/styles/infobox.css b/src/aiidalab_qe/app/static/styles/infobox.css index a25861e42..a66f0c773 100644 --- a/src/aiidalab_qe/app/static/styles/infobox.css +++ b/src/aiidalab_qe/app/static/styles/infobox.css @@ -2,14 +2,42 @@ display: none; margin: 2px; padding: 1em; - border: 3px solid orangered; - background-color: #ffedcc; - border-radius: 1em; - -webkit-border-radius: 1em; - -moz-border-radius: 1em; - -ms-border-radius: 1em; - -o-border-radius: 1em; + border-left: 3px solid #add8e6; + background-color: #d9edf7; } .info-box p { line-height: 24px; } +.info-box.in-app-guide.show { + display: flex !important; +} +.guide ol { + list-style: none; +} +.guide p:not(:last-of-type) { + margin-bottom: 0.5em; +} +.guide-warning { + background-color: #fcf8e3; + border-color: #ffe4c4; + margin-bottom: 1em; +} +.post-guide { + margin: 1em 0; +} +.in-app-guide .alert { + color: black; + margin: 10px 0; + padding: 10px 14px; + border-width: 0; + border-left-width: 3px; +} +.in-app-guide .alert.alert-warning { + border-color: #ffe4c4; +} +.in-app-guide .alert.alert-success { + border-color: #8fbc8f; +} +.in-app-guide h4 { + font-weight: bold; +} diff --git a/src/aiidalab_qe/app/static/templates/guide.jinja b/src/aiidalab_qe/app/static/templates/guide.jinja index d72d7beef..0a1a5bcf1 100644 --- a/src/aiidalab_qe/app/static/templates/guide.jinja +++ b/src/aiidalab_qe/app/static/templates/guide.jinja @@ -42,5 +42,8 @@ For a more in-depth dive into the app's features, please refer to the how-to guides.

+ +

+ Alternatively, you can select one of our in-app guides below to walk through an example use-case.

diff --git a/src/aiidalab_qe/app/structure/__init__.py b/src/aiidalab_qe/app/structure/__init__.py index 998be5cf2..e32e47ecc 100644 --- a/src/aiidalab_qe/app/structure/__init__.py +++ b/src/aiidalab_qe/app/structure/__init__.py @@ -14,6 +14,7 @@ LazyLoadedOptimade, LazyLoadedStructureBrowser, ) +from aiidalab_qe.common.infobox import InAppGuide from aiidalab_widgets_base import ( BasicCellEditor, BasicStructureEditor, @@ -151,6 +152,7 @@ def render(self): ) self.children = [ + InAppGuide(identifier="structure-step"), ipw.HTML("""

Select a structure from one of the following sources and then diff --git a/src/aiidalab_qe/app/submission/__init__.py b/src/aiidalab_qe/app/submission/__init__.py index 344535f3a..e4f745abe 100644 --- a/src/aiidalab_qe/app/submission/__init__.py +++ b/src/aiidalab_qe/app/submission/__init__.py @@ -11,6 +11,7 @@ from aiidalab_qe.app.parameters import DEFAULT_PARAMETERS from aiidalab_qe.app.utils import get_entry_items from aiidalab_qe.common.code import PluginCodes, PwCodeModel +from aiidalab_qe.common.infobox import InAppGuide from aiidalab_qe.common.panel import PluginResourceSettingsModel, ResourceSettingsPanel from aiidalab_qe.common.setup_codes import QESetupWidget from aiidalab_qe.common.setup_pseudos import PseudosInstallWidget @@ -158,6 +159,7 @@ def render(self): ) self.children = [ + InAppGuide(identifier="submission-step"), ipw.HTML("""

Codes

diff --git a/src/aiidalab_qe/app/wrapper.py b/src/aiidalab_qe/app/wrapper.py index a22248fbb..8ecedb45a 100644 --- a/src/aiidalab_qe/app/wrapper.py +++ b/src/aiidalab_qe/app/wrapper.py @@ -1,8 +1,10 @@ from __future__ import annotations import ipywidgets as ipw -import traitlets +import traitlets as tl +from IPython.display import display +from aiidalab_qe.common.guide_manager import guide_manager from aiidalab_qe.common.widgets import LoadingWidget @@ -56,7 +58,16 @@ def enable_toggles(self) -> None: def _on_guide_toggle(self, change: dict): """Toggle the guide section.""" if change["new"]: - self._view.info_container.children = [self._view.guide] + self._view.info_container.children = [ + self._view.guide, + ipw.HBox( + children=[ + self._view.guide_category_selection, + self._view.guide_selection, + ], + layout=ipw.Layout(align_items="baseline"), + ), + ] self._view.info_container.layout.display = "flex" self._view.job_history_toggle.value = False else: @@ -89,14 +100,53 @@ def _on_job_history_toggle(self, change: dict): else: self._view.main.children = self._old_view + def _on_guide_category_select(self, change: dict): + self._view.guide_selection.options = guide_manager.get_guides(change["new"]) + self._update_active_guide() + + def _on_guide_select(self, _): + self._update_active_guide() + + def _update_active_guide(self): + """Sets the current active guide.""" + category = self._view.guide_category_selection.value + guide = self._view.guide_selection.value + active_guide = f"{category}/{guide}" if category != "none" else category + guide_manager.active_guide = active_guide + + def _set_guide_category_options(self, _): + """Fetch the available guides.""" + self._view.guide_category_selection.options = [ + "none", + *guide_manager.get_guide_categories(), + ] + def _set_event_handlers(self) -> None: """Set up event handlers.""" - self._view.guide_toggle.observe(self._on_guide_toggle, "value") - self._view.about_toggle.observe(self._on_about_toggle, "value") - self._view.job_history_toggle.observe(self._on_job_history_toggle, "value") + self._view.guide_toggle.observe( + self._on_guide_toggle, + "value", + ) + self._view.about_toggle.observe( + self._on_about_toggle, + "value", + ) + self._view.job_history_toggle.observe( + self._on_job_history_toggle, + "value", + ) + self._view.guide_category_selection.observe( + self._on_guide_category_select, + "value", + ) + self._view.guide_selection.observe( + self._on_guide_select, + "value", + ) + self._view.on_displayed(self._set_guide_category_options) -class AppWrapperModel(traitlets.HasTraits): +class AppWrapperModel(tl.HasTraits): """An MVC model for `AppWrapper`.""" def __init__(self): @@ -114,7 +164,7 @@ def __init__(self) -> None: from datetime import datetime from importlib_resources import files - from IPython.display import Image, display + from IPython.display import Image from jinja2 import Environment from aiidalab_qe.app.static import templates @@ -184,6 +234,14 @@ def __init__(self) -> None: self.guide = ipw.HTML(env.from_string(guide_template).render()) self.about = ipw.HTML(env.from_string(about_template).render()) + self.guide_category_selection = ipw.RadioButtons( + options=["none"], + description="Guides:", + value="none", + layout=ipw.Layout(width="max-content"), + ) + self.guide_selection = ipw.RadioButtons(layout=ipw.Layout(margin="2px 20px")) + self.job_history = QueryInterface() self.info_container = InfoBox() diff --git a/src/aiidalab_qe/common/guide_manager.py b/src/aiidalab_qe/common/guide_manager.py new file mode 100644 index 000000000..15e313693 --- /dev/null +++ b/src/aiidalab_qe/common/guide_manager.py @@ -0,0 +1,98 @@ +from __future__ import annotations + +from pathlib import Path + +import traitlets as tl +from bs4 import BeautifulSoup, PageElement + +import aiidalab_qe +from aiidalab_qe.app.utils import get_entry_items + + +class GuideManager(tl.HasTraits): + """A global guide manager that loads and manages guide sections.""" + + active_guide = tl.Unicode("none", allow_none=True) + + def __init__(self, *args, **kwargs): + """`GuideManager` constructor.""" + + super().__init__(*args, **kwargs) + guides = Path(aiidalab_qe.__file__).parent.joinpath("guides").glob("*") + self._guides = { + "general": { + guide.stem.split("_", maxsplit=1)[1]: guide.absolute() + for guide in sorted(guides, key=lambda x: x.stem.split("_")[0]) + } + } + + self._fetch_plugin_guides() + + self.content = BeautifulSoup() + + self.observe( + self._on_active_guide_change, + "active_guide", + ) + + @property + def has_guide(self) -> bool: + return self.active_guide != "none" + + def get_guide_categories(self) -> list[str]: + """Return a list of available guides. + + Returns + ------- + `list[str]` + A list of the names of available guides. + """ + return [*self._guides.keys()] + + def get_guides(self, identifier: str) -> list[str]: + """Return a list of available sub-guides. + + Returns + ------- + `list[str]` + A list of the names of available sub-guides. + """ + return [*self._guides[identifier].keys()] if identifier != "none" else [] + + def get_guide_section_by_id(self, content_id: str) -> PageElement | None: + """Return a guide section by its HTML `id` attribute. + + Parameters + ---------- + `content_id` : `str` + The HTML `id` attribute of the guide section. + + Returns + ------- + `PageElement` | `None` + The guide section or `None` if not found. + """ + return self.content.find(attrs={"id": content_id}) # type: ignore + + def _on_active_guide_change(self, _): + """Load the contents of the active guide.""" + if self.active_guide == "none": + self.content = BeautifulSoup() + return + category, guide = self.active_guide.split("/") + guide_path = self._guides[category][guide] + html = Path(guide_path).read_text() if guide_path else "" + self.content = BeautifulSoup(html, "html.parser") + + def _fetch_plugin_guides(self): + """Fetch guides from plugins.""" + entries: dict[str, Path] = get_entry_items("aiidalab_qe.properties", "guides") + for identifier, guides in entries.items(): + if identifier not in self._guides: + self._guides[identifier] = {} + for guide in sorted(guides.glob("*"), key=lambda x: x.stem.split("_")[0]): + stem = guide.stem.split("_", maxsplit=1)[1] + self._guides[identifier][stem] = guide.absolute() + + +guide_manager = GuideManager() diff --git a/src/aiidalab_qe/common/infobox.py b/src/aiidalab_qe/common/infobox.py index 86a7eb26b..5d7b3b79a 100644 --- a/src/aiidalab_qe/common/infobox.py +++ b/src/aiidalab_qe/common/infobox.py @@ -20,3 +20,107 @@ def __init__(self, classes: list[str] | None = None, **kwargs): for custom_class in custom_classes.split(" "): if custom_class: self.add_class(custom_class) + + +class InAppGuide(InfoBox): + """The `InAppGuide` is used to set up toggleable in-app guides. + + Attributes + ---------- + `manager` : `GuideManager` + A local reference to the global guide manager. + `identifier` : `str`, optional + If content `children` are not provided directly, the `identifier` + is used to fetch the corresponding guide section from the guide + currently loaded by the guide manager. + + Raises + ------ + `ValueError` + If neither content `children` or a guide section `identifier` are provided. + """ + + def __init__( + self, + children: list | None = None, + guide_id: str = "", + identifier: str = "", + classes: list[str] | None = None, + **kwargs, + ): + """`InAppGuide` constructor. + + Parameters + ---------- + `children` : `list`, optional + The content children of this guide section. + `guide_id` : `str`, optional + The associated guide id to be used in conjunction with content children. + If none provided, the widget-based guide section will be shown for all + guides. + `identifier` : `str`, optional + If content `children` are not provided directly, the `identifier` + is used to fetch the corresponding guide section from the guide + currently loaded by the guide manager. + `classes` : `list[str]`, optional + One or more CSS classes. + """ + from aiidalab_qe.common.guide_manager import guide_manager + + self.manager = guide_manager + + super().__init__( + classes=[ + "in-app-guide", + *(classes or []), + ], + **kwargs, + ) + + if children: + self.guide_id = guide_id + self.children = children + self.identifier = None + elif identifier: + self.guide_id = None + self.children = [] + self.identifier = identifier + else: + raise ValueError("No widgets or path identifier provided") + + self.manager.observe( + self._on_active_guide_change, + "active_guide", + ) + + # This manual toggle call is necessary because the guide + # may be contained in a component that was not yet rendered + # when a guide was selected. + self._on_active_guide_change(None) + + def _on_active_guide_change(self, _): + self._update_contents() + self._toggle_guide() + + def _update_contents(self): + """Update the contents of the guide section.""" + if not self.identifier: + return + html = self.manager.get_guide_section_by_id(self.identifier) + self.children = [ipw.HTML(str(html))] if html else [] + + def _toggle_guide(self): + """Toggle the visibility of the guide section.""" + self.layout.display = ( + "flex" + if self.children + and ( + # file-based guide section + (self.identifier and self.manager.has_guide) + # widget-based guide section shown for all guides + or (not self.guide_id and self.manager.has_guide) + # widget-based guide section shown for a specific guide + or self.guide_id == self.manager.active_guide + ) + else "none" + ) diff --git a/src/aiidalab_qe/guides/0_basic.html b/src/aiidalab_qe/guides/0_basic.html new file mode 100644 index 000000000..b2edb75b1 --- /dev/null +++ b/src/aiidalab_qe/guides/0_basic.html @@ -0,0 +1,164 @@ +
+ You've activated the basic in-app guide. Follow along below to learn the basic + features of the Quantum ESPRESSO app. +
+ +
+ In this step, you can select a structure as follows: +
    +
  • Upload file: upload a structure file from your computer.
    • +
  • OPTIMADE: search for structures in the OPTIMADE database.
    • +
  • + AiiDA database: search for structures in your AiiDA database. +
    • +
  • + From Examples: select a structure from a list of example + structures. +
    • +
+ Once selected, you may inspect the structure. You can also edit the structure + using the available structure editors. When done, you can choose to modify the + structure label and/or provide a description. These will be attached to the + input structure node in your AiiDA database. When you are ready, click + "Confirm" to proceed to the next step. +
+
+

Tasks

+
    +
  1. Click on the From examples tab
    2. +
  2. Select Gold from the dropdown list
    3. +
  3. Click the Confirm button to proceed.
    4. +
+
+
+ Warning: If the confirmed structure is not yet stored in the AiiDA + database, it will be stored automatically when you proceed to the next step. +
+
+ Warning: Changes after confirmation will unconfirm this step and + reset the following steps. +
+
+ +
+ In this step, we define the workflow tasks, including structure relaxation and + which properties to compute, and select the parameters of the calculations. +
+

Tasks

+
    +
  1. Select Full geometry relaxation
    2. +
  2. Open Step 2.1 to select properties
    3. +
  3. Open Step 2.2 to customize parameters
    4. +
  4. Click Confirm to proceed
    5. +
+
+
+ Note: Changes after confirmation will unconfirm this step and reset + the following steps. +
+
+ +
+ Here we select the properties to calculate. +
+ Select Electronic band structure and + Projected density of states (PDOS) +
+
+ +
+ Here we can customize the calculation parameters. +
+ Click on each tab to customize its settings. +
+
+ +
+ The basic settings panel provides top-level calculation settings including the + electronic and magnetic properties of the material. It also provides a choice + of three protocols that pre-configure many calculation settings, balancing + speed with accuracy. +
Select the fast protocol
+
+ Note: Due to the limited resources provided for the demo server, we select + the fast protocol to reduce the cost of the calculation. +
+
+ +
+ The Advanced settings allow you to finely tune the calculation. +
+ In this walkthrough, we will not modify advanced settings and proceed with + the defaults. +
+
+ +
+ Here we configure the settings for computing the band structure. +
Check Fat bands calculation
+
+ +
+ Here we configure the settings for computing the projected density of states, + or PDOS. +
+ In this walkthrough, we will not modify pdos settings and proceed with the + defaults. +
+
+ +
+ In this step, we define the resources to be used in the calculation. The + global resources are used to define resources across all workflow + calculations. Optionally, you can override the resource settings for specific + calculations. +
+

Tasks

+
    +
  1. Select computational resources
    2. +
  2. Add a description of the calculation
    3. +
  3. Click Submit to proceed
    4. +
+
+
+ +
+ In this step, we can monitor the calculation and view its results. A summary + of calculation parameters is also provided. Raw input and output files may be + downloaded, as well as an AiiDA archive containing the full calculation + provenance. +
+

Tasks

+
    +
  1. + In the process tree, click on the root QeAppWorkChain node +
    2. +
  2. (optional) review the calculation parameters
    3. +
  3. Click on the Final Geometry tab
    4. +
  4. + When the structure relaxation is finished, click on + Load results to view the final structure geometry +
    5. +
  5. + Repeat the last two steps for the Bands and PDOS tabs +
    6. +
+
+
+ +
+ This concludes the basic Quantum ESPRESSO in-app guide. +
+

Exercises

+
    +
  1. + Download the raw input and output files for further analysis +
    2. +
  2. + Download the AiiDA archive to store the full calculation + provenance +
    3. +
  3. Explore the AiiDA database to view the calculation history
    4. +
+
+
diff --git a/src/aiidalab_qe/guides/1_advanced.html b/src/aiidalab_qe/guides/1_advanced.html new file mode 100644 index 000000000..234d1fa55 --- /dev/null +++ b/src/aiidalab_qe/guides/1_advanced.html @@ -0,0 +1,16 @@ +
+ You've activated the advanced in-app guide. Follow along below to learn how to + use the more advanced features of the Quantum ESPRESSO app. +
+ +
Advanced example
+ +
Advanced example
+ +
Advanced example
+ +
Advanced example
+ +
+ This concludes the advanced Quantum ESPRESSO in-app guide. +
diff --git a/src/aiidalab_qe/plugins/bands/__init__.py b/src/aiidalab_qe/plugins/bands/__init__.py index 2cc72a868..3c2a97aca 100644 --- a/src/aiidalab_qe/plugins/bands/__init__.py +++ b/src/aiidalab_qe/plugins/bands/__init__.py @@ -1,4 +1,6 @@ # from aiidalab_qe.bands.result import Result +from pathlib import Path + from aiidalab_qe.common.panel import PluginOutline from .model import BandsConfigurationSettingsModel @@ -27,4 +29,5 @@ class BandsPluginOutline(PluginOutline): "model": BandsResultsModel, }, "workchain": workchain_and_builder, + "guides": Path(__file__).parent / "guides", } diff --git a/src/aiidalab_qe/plugins/bands/guides/0_basic.html b/src/aiidalab_qe/plugins/bands/guides/0_basic.html new file mode 100644 index 000000000..9af66d3e0 --- /dev/null +++ b/src/aiidalab_qe/plugins/bands/guides/0_basic.html @@ -0,0 +1,10 @@ +
+ You've activated the basic bands in-app guide. Follow along below to learn how + to use the Quantum ESPRESSO app to run a simple band structure calculation. +
+ +
Bands example
+ +
Bands example
+ +
Bands example
diff --git a/src/aiidalab_qe/plugins/bands/setting.py b/src/aiidalab_qe/plugins/bands/setting.py index efbbdb37b..225aac3ef 100644 --- a/src/aiidalab_qe/plugins/bands/setting.py +++ b/src/aiidalab_qe/plugins/bands/setting.py @@ -2,6 +2,7 @@ import ipywidgets as ipw +from aiidalab_qe.common.infobox import InAppGuide from aiidalab_qe.common.panel import ConfigurationSettingsPanel from aiidalab_qe.plugins.bands.model import BandsConfigurationSettingsModel @@ -26,6 +27,7 @@ def render(self): ) self.children = [ + InAppGuide(identifier="bands-settings"), ipw.HTML("""

Settings

diff --git a/src/aiidalab_qe/plugins/pdos/setting.py b/src/aiidalab_qe/plugins/pdos/setting.py index 462f3aa66..c4cf0f301 100644 --- a/src/aiidalab_qe/plugins/pdos/setting.py +++ b/src/aiidalab_qe/plugins/pdos/setting.py @@ -2,6 +2,7 @@ import ipywidgets as ipw +from aiidalab_qe.common.infobox import InAppGuide from aiidalab_qe.common.panel import ConfigurationSettingsPanel from .model import PdosConfigurationSettingsModel @@ -107,6 +108,7 @@ def render(self): ) self.children = [ + InAppGuide(identifier="pdos-settings"), ipw.HTML("""

Settings

diff --git a/tests/test_infobox.py b/tests/test_infobox.py index 892335da9..84289bdbb 100644 --- a/tests/test_infobox.py +++ b/tests/test_infobox.py @@ -1,8 +1,7 @@ -from aiidalab_qe.common.infobox import InfoBox - - def test_infobox_classes(): """Test `InfoBox` classes.""" + from aiidalab_qe.common.infobox import InfoBox + custom_classes = ["custom-1", "custom-2 custom-3"] infobox = InfoBox(classes=custom_classes) assert all( @@ -14,3 +13,36 @@ def test_infobox_classes(): "custom-3", ) ) + + +def test_in_app_guide(): + """Test `InAppGuide` class.""" + import ipywidgets as ipw + + from aiidalab_qe.common.guide_manager import guide_manager + from aiidalab_qe.common.infobox import InAppGuide + + in_app_guide = InAppGuide(children=[ipw.HTML("Hello, World!")]) + assert all( + css_class in in_app_guide._dom_classes + for css_class in ( + "info-box", + "in-app-guide", + ) + ) + assert in_app_guide.children[0].value == "Hello, World!" + + assert in_app_guide.layout.display == "none" + guide_manager.active_guide = "general/basic" + assert in_app_guide.layout.display == "flex" + guide_manager.active_guide = "general/advanced" + assert in_app_guide.layout.display == "flex" + in_app_guide.guide_id = "general/advanced" + guide_manager.active_guide = "general/basic" + assert in_app_guide.layout.display == "none" + guide_manager.active_guide = "general/advanced" + assert in_app_guide.layout.display == "flex" + + guide_manager.active_guide = "general/basic" + in_app_guide = InAppGuide(identifier="guide-warning") + assert "You've activated the basic in-app guide" in in_app_guide.children[0].value diff --git a/tests/test_wrapper.py b/tests/test_wrapper.py index 609fa40d8..e4eed6a1c 100644 --- a/tests/test_wrapper.py +++ b/tests/test_wrapper.py @@ -18,7 +18,7 @@ def test_guide_toggle(self): self.controller._on_guide_toggle({"new": True}) self._assert_guide_is_on() self.controller._on_guide_toggle({"new": False}) - self._assert_no_guide_info() + self._assert_no_info() def test_about_toggle(self): """Test about_toggle method.""" @@ -27,13 +27,13 @@ def test_about_toggle(self): self.controller._on_about_toggle({"new": True}) self._assert_about_is_on() self.controller._on_about_toggle({"new": False}) - self._assert_no_guide_info() + self._assert_no_info() def test_toggle_switch(self): """Test toggle_switch method.""" self._instansiate_mvc_components() self.controller.enable_toggles() - self._assert_no_guide_info() + self._assert_no_info() self.controller._on_guide_toggle({"new": True}) self._assert_guide_is_on() self.controller._on_about_toggle({"new": True}) @@ -41,11 +41,11 @@ def test_toggle_switch(self): self.controller._on_guide_toggle({"new": True}) self._assert_guide_is_on() self.controller._on_guide_toggle({"new": False}) - self._assert_no_guide_info() + self._assert_no_info() def _assert_guide_is_on(self): """Assert guide is on.""" - assert len(self.view.info_container.children) == 1 + assert len(self.view.info_container.children) == 2 assert self.view.guide in self.view.info_container.children def _assert_about_is_on(self): @@ -53,7 +53,7 @@ def _assert_about_is_on(self): assert len(self.view.info_container.children) == 1 assert self.view.about in self.view.info_container.children - def _assert_no_guide_info(self): + def _assert_no_info(self): """Assert no info is shown.""" assert len(self.view.info_container.children) == 0