Implement path for in-app guides

[edan-bainglass]

Based on #967

This PR adds a mechanism for adding in-app guides meant as example use-cases for users. The mechanism leverages a global instance of the GuideManager, which tracks the current selected guide in an active_guide traitlet, which is observed by all InAppGuide instances. Instances are placed throughout the app with unique identifiers. Additional placeholders may be added by plugin developers within their defined panels.

Usage

In-app guide widgets can be added anywhere as follows:

from aiidalab_qe.common.infobox import InAppGuide

example = InAppGuide(
    children=[
        ipw.HTML("An example in-app guide."),
    ],
    guide_id="general/basic",
)

This defines the guide explicitly, providing hard-coded content, which is useful for generic guide sections that are useful for any guide. Children can be any widget supported by ipywidgets. This allows developers to customize the content of the guide as they wish. The guide_id refers to the associated guide and is used to toggle the guide section on/off.

However, for specific guide content, a more flexible approach is

from aiidalab_qe.common.infobox import InAppGuide

example = InAppGuide(identifier="structure-step")

Here, the guide is defined from content fetched by an HTML id attribute from the currently loaded guide (HTML document) in the guide manager corresponding to the active (selected) guide. The HTML document is parsed using beautiful soup.

In either case, CSS classes can be provided to the InAppGuide constructor to override the behavior of the info-box and in-app-guide CSS classes.

example = InAppGuide(
    identifier="structure-step",
    classes=["custom1", "custom2", etc.],
)

This allows developers to control top-level styles for the guide. Styles internal to the guide are more easily controlled directly in the guide HTML documents.

External guides

The app defines internal guides in src/aiidalab_qe/guides. External guides may be added by plugin developers using the same entry point system already used in plugins. Developers simply add a guides key to their plugin definition with a value pointing at the path of their guides directory. The guide manager will pick these up on app start and add them to the list of available guides.

Comments regarding external guides

Entry point

We may consider enforcing a structure here, specifying that external guides must be provided at the root level of the plugin.

• Pro: developers don't need to bother with adding the new guides key
• Con: rigid placement and slightly more complex approach to finding the guides directory (easy if there is a simple means of obtaining the path of the plugin directory)

update

Current decision (discussed with @superstar54) is to require the guides key in the entry point.

Uniqueness

In the current implementation, there is a risk an external guide developer names a guide identically to an existing internal/external guide. To avoid this, the plugin identifier can be used as a prefix when storing guides in the manager. In the app, we could consider displaying guides by category. There are various means of achieving this cleanly. Open to discussion.

update

Current approach is to indeed use the plugin identifier as a prefix. This results in the following:

[codecov]

Codecov Report

Attention: Patch coverage is 87.37864% with 13 lines in your changes missing coverage. Please review.

Project coverage is 68.55%. Comparing base (5949bdf) to head (dfa9884).
Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/aiidalab_qe/app/wrapper.py	69.23%	8 Missing ⚠️
src/aiidalab_qe/common/guide_manager.py	90.24%	4 Missing ⚠️
src/aiidalab_qe/common/infobox.py	96.15%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #763      +/-   ##
==========================================
+ Coverage   68.26%   68.55%   +0.29%     
==========================================
  Files         110      111       +1     
  Lines        6211     6307      +96     
==========================================
+ Hits         4240     4324      +84     
- Misses       1971     1983      +12     

Flag	Coverage Δ
python-3.11	68.54% <87.37%> (+0.27%)	⬆️
python-3.9	68.58% <87.37%> (+0.29%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[superstar54]

Hi @edan-bainglass , is this PR ready for review? I like the design, and I am looking forward to having it in the APP.

[edan-bainglass]

@superstar54 it is :) The failed tests are due to a chain of yet-to-be-merged PRs all the way back to aiidalab/aiidalab-widgets-base#624, which @danielhollas is reviewing.

[superstar54]

When reviewing this PR, do I need to switch aiidalab/aiidalab-widgets-base#624?.

[edan-bainglass]

If you're testing locally, then yes.

[superstar54]

Very nice in-app guide! The style is also pretty. I added a few suggestions in the comments.

Could you also add a guide for step 4.

[superstar54]

Suggested change

	<li>Select resources</li>
	<li>Select resources in the Global resources tab</li>

[superstar54]

Since "Full geometry" is the default, consider select "Atomic positions"

[superstar54]

Similar to the advacned settings,

Suggested change

	<div class="alert alert-success">???</div>
	<div class="alert alert-success">In this walkthrough, we will not modify the pdos settings and proceed with the defaults.</div>

[superstar54]

Maybe also add a description of the calculation before submitting.

[edan-bainglass]

Very nice in-app guide! The style is also pretty. I added a few suggestions in the comments.

Could you also add a guide for step 4.

Thanks @superstar54. Note that I will make no comments regarding the actual content of the guides, as the current content is only a draft to give @giovannipizzi and @cpignedoli a sense of how it works. I will work with them in an immediately following PR to iron out the actual content, at which point, we will also cover step 4 🙂

Since all your comments above ARE regarding content, I take it you approve of the mechanism itself. Per our discussion, I will update the PR to handle uniqueness as suggested in the PR description.

[danielhollas]

Per our discussion, I will update the PR to handle uniqueness as suggested in the PR description.

LMK when you're done with that and I can have a final look (but feel free to merge anytime / don't feel block by me)

[edan-bainglass]

@danielhollas ready to review. I implemented guide uniqueness in the last commit. Also in that commit is a mechanism for ensuring intended guide order by inspecting the HTML file name, which is now required to include a #_ prefix to indicate the intended order, which I parse. I did this sort of quick, so if you think of a better approach, do share 🙂

[edan-bainglass]

@superstar54 I added placeholders in step 4 and after the wizard. Again, the text is not important, nor is the placement of the guide widgets. We will update these with one final PR once @cpignedoli and @giovannipizzi agree on the text. No changes in this last commit regarding the mechanism, so if you already agree with it, let me know and we merge 🙏

[superstar54]

The structure looks good to me! Please ask others for the texts.

[edan-bainglass]

The structure looks good to me! Please ask others for the texts.

Good. I'm not sure while the docker image is failing though. Can you have a look? 🙏🙏🙏

[edan-bainglass]

@danielhollas this and several other PRs are failing at building the docker image. Could you please have a look? 🙏

[danielhollas]

@edan-bainglass appologies, I will not have time, I am leaving for holidays tomorrow and will be mostly off-line this and next week.

[edan-bainglass]

@edan-bainglass appologies, I will not have time, I am leaving for holidays tomorrow and will be mostly off-line this and next week.

Okay. No worries. Enjoy the holidays 🙂