[Feature]: Adding Engaging Visual Elements/Map in Documentation

[Fe-r-oz]

Feature Description

Importance

4

What does this feature affect?

• quantum system construction
• problem setup
• problem solution
• problem performance
• solution analysis
• plotting
• documentation
• tests
• other (please specify below)

Other information

Adding schematics like this allows the beginners to get a complete overview of the package in an instant. It also makes the documentation more engaging to read without having to explore the API.

[aarontrowbridge]

hey @Fe-r-oz sorry we are just seeing this, we had something like this before, but this is MUCH clearer, we will probably merge it in later this week

[Fe-r-oz]

Hi @aarontrowbridge , No problem. I would like to have your thoughts on another approach. Let's call it a docstring based approach instead of a hard coded figure based approach.

I think in the long run, a better, maintainable solution would be by using dynamic schematics created in docstring using Mermaid. This means that whenever a new functionality is added, we can just add update the code with ease instead of using hard coded schematics.

Here is a rough version with default color scheme in Mermaid attached below. As it's a screenshot attached below, it's not clear, But it will be much clearer when rendered via browser.

This approach might not be as fancy as the one above but it's maintainable and easily updateable. What do you suggest?

I can submit a polished PR of this approach later this week. Please do let me know if there is any other flowcharts we can add, refer me to the paper (if any) and I will look into it as well

[andgoldschmidt]

Mermaid seems to flatten the hierarchical structure of the package. @Fe-r-oz Is this expected, or an artifact of not using the browser? For example, we see here that ProblemTemplate and QuantumUtils are repeated many times, but in the original post the hierarchy looks correct and easy to interpret.

[Fe-r-oz]

Indeed, we don't want the labels to be repeated many times. Thanks for pointing that out. I have fixed it.

How about this (screenshot taken from browser)?

[andgoldschmidt]

That looks good! Is there a way to tag what functions appear in the preview? Perhaps, a flag in the docstring parsed by the dynamic schematic that says "yes, this function should be displayed".

My reason is that not all exported functions have the same priority for users. For example, isovec_unitary_fidelity is useful to export, but most users will interact with unitary_fidelity.

[Fe-r-oz]

Option 1

Option 2

Option 3: We can only include unitary fidelity.

Mermaid flowcharts is typically written in HTLML format <div class ="Mermaid"> ...</div> so there is no explicit tag. Nevertheless, I have presented 3 options which are close to your requirements. Please let me know which sounds good.

[aarontrowbridge]

I think isovec_unitary_fidelity should be treated as a unique function. This looks good though!

[aarontrowbridge]

i think including all exported functions is good. is there a way to attach hrefs to the source code or docs?

[Fe-r-oz]

Thanks for your suggestion.

In the """ [docs](url) """, I think we can add the href with [Preferred Title](url) similar to how we do it in .md.

[andgoldschmidt]

After the codebase refactor this issue is more relevant at the level of Piccolo.jl, and should be re-opened there.