📝 Integrate updated cheat sheet into main docs

[GeigerJ2]

This PR integrates an updated version of the cheat sheet into the intro section of the main docs.

The main changes to the SVG file are:

• I put the verdi graph in the beginning, as the first contact of people with AiiDA is likely via the verdi command line interface. Outdated commands were removed and the commands that are shown are changed to (I think) more useful examples. This included removing the show/list/delete options that are implemented for most verdi commands and were shown numerous times. Instead, they are mentioned via the footnote.
• This freed up some space for a panel with additional verdi commands. These should ideally be useful commands that are not included in the base tutorial, and/or mentioned in the graph (please share feedback here if you think something is missing or unnecessary - I just added the examples I could think of from the top of my head; the process and calcjob dump are anticipated and don't exist yet in main)
• Next comes the inheritance hierarchy and the Python imports. The long list of attributes and methods is moved to the second page instead (I think this could be overwhelming, is far from complete, and people who are already that committed will likely be digging further into the documentation and/or src anyway)
• Instead, I added a panel with additional web resources, all as clickable links pointing to the relevant URLs
• Most of the floating text elements are removed, as these are likely overlooked next to the graphs and boxes and flashy colors. The relevant information was either included in the respective boxes (e.g. for the Python imports) or added to the source code examples (e.g. the QueryBuilder import).
• I revised the tiles that show attributes and methods of certain classes, in particular:
  • Node methods were updated to show access via node.base to reflect the current API.
  • Properties that were previously shown for CalcJobNode are moved to the more general ProcessNode, while the remaining CalcJobNode methods are more specific.
  • The main elements for constructing WorkChains are added. Note that this is done for the WorkChain process, not the WorkChainNode, as I didn't find additional methods that seemed relevant to add, as they are already included in the tile for ProcessNode. Like this, people get at least an introduction into the terminology required when constructing WorkChains, e.g. the outline and context.
  • The Data and ArrayData tiles were removed
  • KpointsData and StructureData remained basically the same
• The overall layout was changed from vertical (2 pages) to horizontal so that the whole figure can be shown in the readthedocs page and in the browser
• Hyperlinks were added to the verdi graph (text elements to the second level; pointing to the verdi reference pages in the docs), the AiiDA node subclasses graph (all text elements; pointing to relevant sections in the docs, mainly Topics and How-To), as well as the additional resources (pointing to the GitHub repos).

In the rst file, a link to the SVG is included, so that the figure is displayed directly on the page (I didn't manage to integrate the SVG source code directly into the rst, but I also don't think it's necessary). Clicking on the image opens it directly in the browser. A download link to the PDF in the typical 2-page layout for printing is also included.

One could add more hyperlinks, but I think for now it's fine. And before I continue to frantically align SVG elements, better to get it out there. Lastly, please rebase before merge :D

Pinging @khsrali, @sphuber, @mbercx and @giovannipizzi for feedback if anybody has the time. Thanks!

[GeigerJ2]

Thanks for the feedback, @sphuber! Regarding your points:

What are the other PDF versions for (cheatsheet1.pdf and cheatsheet2.pdf)?

These were just intermediate files and can be removed. As the layout in the SVG is horizontal, I exported each page separately and merged them with pdftk.

Why cheatsheet_h.svg and cheatsheet_v.pdf?

Same reason here. I just had the labels as I experimented with multiple files. I'll remove them, so it'll just be cheatsheet.pdf and cheatsheet.svg.

The hitboxes of the links on the second line in the "additional web resources" are very small. Most part of the text is not clickable. Can this be fixed?

Hm, that's weird. The whole text elements should be clickable. In the PDF, for me, it's fine (aka it works on my machine). I'll make the text and boxes into groups and set the anchor there, that should fix it and correspond better with the elements being clickable buttons. Did you try it with the PDF locally or with the SVG in the browser?

It would be good if code can be put in a monospaced font

It should already be? At least in the text boxes, code is monospaced (Ubuntu Mono font). Do you mean in the graphs?

Fix what went astray: should really be verdi daemon stop\nverdi process repair\nverdi daemon start.

Alright, updated!

"ProcessNode attributes": there is still ".etc?"

Ah, yes, I see how that might be confusing. The reason for "etc." was that these are not all the properties, and I added the question mark as the code is phrased like "is finished?", "is stored?" :D I'll replace it with a "..."

verdi storage list is not an actual command

Must've been a typo.

verdi calcjob/process dump don't exist, yet...

They should be there in a few days!

I noticed that you included the version number in the cheatsheet. Although that might be useful to have, it is for sure that we are going to forget to update it. Is there a way we can automatically update it? Otherwise maybe it is best to remove it?

A bit pessimistic, but probably an accurate assessment :D That was just added as it was included in the previous version of the cheat sheet. Though, as part of the aiida-tutorials that was also more static. One could probably update it automatically, but in the case that it becomes actually relevant, i.e. if a newer AiiDA version changes the API, then we'd also have to update that in the cheat sheet, not just the version number. So, for me, it's also fine to remove it.

[sphuber]

It should already be? At least in the text boxes, code is monospaced (Ubuntu Mono font). Do you mean in the graphs?

I just checked and the PDF does render correctly, but the svg in the browser doesn't show the monospaced fonts:

Not sure if that is a problem of the SVG or the OS/browser. But I see the same behavior on both Firefox and Edge on Windows 11.

[GeigerJ2]

Not sure if that is a problem of the SVG or the OS/browser. But I see the same behavior on both Firefox and Edge on Windows 11.

Then it might be that the font (Ubuntu Mono) is not available on Windows. I'll look for a monospaced font that is available on both systems. Alternatively, one could also link the exported PDF instead of the SVG.

[sphuber]

Do you want to wrap this one up @GeigerJ2 ? I think for me the open action points are:

• Only keep one svg and one pdf (is there a reason to have svg in landscape and the pdf in portrait? Why not use the some orientation for both?) Can simply convert the svg directly to a pdf with something like Inkscape (has a CLI).
• Remove the version number

Then this can be merged from my side. Thanks

[GeigerJ2]

Yeah, in principle this can be wrapped up. I just need to make sure the chosen monospaced font works on all OSs, or (and this might be my preferred solution) I just link the rendered PDF rather than the SVG. I think linking the SVG in the rst file was just done as the original idea was to directly implement the vector graphic in the rendered page, but if it works by just linking the compiled PDF, no need for extra headache. I have all the other changes applied locally, just holding off as verdi process/calcjob dump isn't merged yet, and it's contained in the cheat sheet.

[GeigerJ2]

Just to add here the reason for having the cheat sheet in both horizontal and vertical layout: For displaying on screen, I think horizontal layout is better, as one can see both pages directly at a glance (integrated into the rst), while for printing a vertical two-page layout might be preferred, as it allows for duplex printing (when following the download link).

[sphuber]

@GeigerJ2 having trouble with git rebase? 😅

[GeigerJ2]

@GeigerJ2 having trouble with git rebase? 😅

Yeah, I think it's because I'm using git worktrees, and rebasing the branch from the respective git worktree folder causes this mess... Almost convinced to ditch the approach, but I don't want to give @mbercx this victory yet :D

[GeigerJ2]

Never happened, nothing to see here, just added one commit 👀 (Well, now the other commits are missing. I'll have another look tomorrow.)

[GeigerJ2]

Alright, this should be ready for merge, and I think it would be nice to include in the v2.6 release. I addressed your comments, @sphuber, could you please take it for another spin?

On the page, it's now showing the image as PNG (embedding the PDF didn't work easily without using raw HTML; and neither did this work as I intended). The image target points to the PDF in horizontal layout for nice display on the screen, meaning that fonts should show correctly irrespective of OS and browser, and the hyperlinks should work. I had to add this PDF to _static, as it's not directly referenced via image, so it's not being copied over to build/html/_images otherwise. The download link points to the PDF in vertical, two-page layout to allow for two-sided printing. I left the labels _h and _v for the two PDFs to avoid confusion. While this requires adding two PDF files, I think the horizontal on-screen display and the two-page download would be nice to have. I removed verdi archive dump, as that's a feature that we anticipate and will start working on soon, but it won't make it into this release.

Lastly, can we clean up/squash the commits (i.e. to remove the merge-commit, as to not infuriate @mbercx) when doing the merge, or does that require an interactive rebase locally (still having PTSD from my former two fuck-ups :D). Thanks!