aiida-tutorials icon indicating copy to clipboard operation
aiida-tutorials copied to clipboard

👌 IMPROVE: Update the AiiDA cheat sheet

Open mbercx opened this issue 3 years ago • 2 comments

Would be good to check and update the cheat sheet for the tutorial, see:

https://aiida-tutorials.readthedocs.io/en/tutorial-2021-intro-week_a/_downloads/5f69c3f9ce1f31f1f959b3da46fdc99d/cheatsheet.pdf

Also see this issue on aiida-core:

https://github.com/aiidateam/aiida-core/issues/4506

mbercx avatar Jun 08 '21 18:06 mbercx

Just started looking at this. Apart from adding core prefixes, updating/removing deprecated methods and adding hyperlinks, if anybody more familiar with the AiiDA changelog since v1.0.0 has some input, that could be useful, as well :)

GeigerJ2 avatar Feb 29 '24 08:02 GeigerJ2

Alright, so I applied some (what I would consider) improvements today. I'm not fully done with my intended changes, but still wanted to obtain some feedback here before continuing. So I thank you in advance already :)

The updated svg and pdf can be found in my commit, but there's a screenshot below here, as well.

The main changes 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 workchain 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)

Some things that still remain:

  • Update the attributes and methods of the second page to be consistent with the current API of AiiDA (green boxes are markers for myself)
  • Currently, clickable links are included for the second level of the verdi graph (pointing to the latest AiiDA Command Line Reference sections on readthedocs), as well as the online resources. Ideally, more parts should be clickable if possible, and point to relevant pages of the How-To/Topics/Reference, or tutorials. For example, the snippet WorkflowFactory("quantumespresso.pw.bands") could point to the relevant workflows section of the aiida-tutorials where the snippet actually appears. Like this, the cheat sheet could nicely guide users to further resources for each part.

image

GeigerJ2 avatar Mar 01 '24 18:03 GeigerJ2