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

📝 DOCS: Better/quicker highlighting of useful resources

Open GeigerJ2 opened this issue 6 months ago • 0 comments

Describe the current issue

Alright, so this might be one of the last issues @khsrali and I will raise here regarding the documentation for now 😅 One thing that was recently brought up by @bastonero on Discourse is that it would be nice to have some kind of CLI cheat sheet. The reason being that there are quite some useful commands that one might not be aware of when starting out. While the documentation is extensive and basically everything can be found there, it might be, for that very reason, a bit overwhelming for a beginner, leading to some useful tools being overlooked, thus complicating the adaptation. The issue is also not limited to the CLI, but other resources, as well - to give some examples:

  • verdi calcjob gotocomputer/inputcat/outputcat
  • verdi devel rabbitmq tasks analyze --fix
  • A pointer to the location of the config file (e.g. to debug possible postgres issues)
  • The fact that caching exists (at least when I started, I wasn't aware that it was a thing, though, now it should be more obvious, with it being mentioned in the verdi process outputs)
  • The possibility to use YAML files to define protocols and set configurations
  • The AiiDA resource registry
  • The AiiDA plugin cookie cutter
  • AiiDA-project

Describe the solution you'd like

Now, of course, these points depend on the trajectory each person had when learning AiiDA, and the way they use it now, but we could compile some kind of "wish I'd known that sooner" list - possibly open it as a discussion on Discourse to ask users for input?

Personally, I am a big fan of the AiiDA cheat sheet, and feel like it could be a nice place to compile such information. There already are open PRs (here and here) to update the cheat sheet, make it more general, and integrate it into the main documentation, so we could combine the tasks. The idea was also brought up to convert it into an interactive webpage, though, even providing clickable links in the svg/pdf file where applicable could be a quick solution. Lastly, I think it would be nice to have a panel for the cheat sheet (and/or other resources, such as demos) on the readthedocs landing page, so that they are directly visible at a glance. Curious to hear your thoughts on this!

GeigerJ2 avatar Feb 15 '24 20:02 GeigerJ2