Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

📝 DOCS: Better/quicker highlighting of useful resources #6290

Open
GeigerJ2 opened this issue Feb 15, 2024 · 1 comment · May be fixed by #6644
Open

📝 DOCS: Better/quicker highlighting of useful resources #6290

GeigerJ2 opened this issue Feb 15, 2024 · 1 comment · May be fixed by #6644

Comments

@GeigerJ2
Copy link
Contributor

GeigerJ2 commented Feb 15, 2024

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!

@agoscinski
Copy link
Contributor

Some of the information in the cheat sheet I like a lot. What I don't like is that this is a pdf which is not great for version control, and that it will need frequent updates. I think the main purpose of a cheat sheet is to quickly get an overview of all important aspects of aiida. Then why can't it be just a compressed getting started page similar as the one in aiida-workgraph. aiida-core's introduction page is at the moment too high-level to be a getting started page for users. I can see that a pdf can be more compressed in space than a doc page, but I think the additional maintenance will result in it never being up to date. So would not a compressed getting started page with all the information in the cheat sheet, do also the job?

Also I wonder, regarding the nested trees that the cheatsheet shows, can't we make this information automatically accessible in the CLI with an additional command? Then it is autogenerated and is always up to date (and hopefully needs less maintenance)

verdi help nodetree
verdi help verditree
verdi help node <DATA_TYPE> # e.g. core.strucure
verdi help cheatsheet # an CLI cheat sheet to highlight very useful commands

I am using the help command which can be accessed anyway with verdi --help. The design of the CLI command would be a different discussion.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants