Refresh documentation

[sergisiso]

Here are some ideas to update the PSyclone documentation on readthedocs, this follows two purposes:

• [x] Introduction needs re-write to explain the generic "code generation" capabilities
• [ ] Shorten the menu to bring the Developers and Reference guide to the same page (when not reading carefully its easy to miss that those exist).
  • [ ] The getting going optional dependencies should be moved to the developers section
  • [ ] Parts of PSyIR and LFRic should be moved to the right User section
• [ ] I would simplify the advanced installation aspects of "Getting going" and move them "System-specifc set-up for Users" (see #467). Instead I would just add a couple of examples of transforming simple code snippets (one generic and one psykal) and their outputs to show a general idea of a psyclone workflow, with references to all the more advanced sections.
• [ ] Tutorial is quite short, maybe it can be merged with Examples and be "Tutorial and Examples"
• [ ] Libraries - This could be moved/merged to the PSyData API. And maybe call the page "Instrumentation Tools"? Also when expanding this section it would be good that the sub-menu had each tool listed. Maybe the "Profiling" should be moved inside this page? (see #1206)
• [x] I think that PSyKAl needs an introduction page with a global explanation of the kernel-based parallelism model before explaining each layer (This could be taken from the Introduction page - maybe some time ago it was following more clearly from there?).
• [ ] The PSyIR section need to be merged with the developers_guide PSyIR section, right now its difficult to predict where different pieces of information live.
• [ ] Line-length is already explained in "the PSyclone command" and API/reference guide, so I would deleted or move missing parts there.
• [x] Configuration should be moved to the top section (after "The PSyclone command")
• [ ] The "Fortran naming conventions" should be moved to the LFRic and Gocean relevant sections. I think the same is true for the "Distributed Memory" page?
• [ ] API is the reference-guide? if we bring the reference-guide as a page here it would substitute API?
• [ ] (If we do all the previous) Should we move "PSyclone kernel tools" and "PSyKE" to PSyKAl region and PSyData/Instrumentation Tools to "PSyclone transformations" region, and get rid of the "Utilities and Conventions"?

What do you think? Any other re-organization changes that you would do?

[hiker]

I basically agree. The one thing is point 11: I am not sure about is PSyKE - shouldn't that just go into the (new) Instrumentation Tools? And I think that section would be more than long enough to have its own chapter (and not part of "Psyclone transformations".

Obviously, anything with psydata has a transformation ;) But I would prefer if it is listed in the "PSyclone transformations", with just a reference to the corresponding section in the Instrumentation chapter.

One other thing which might be worth addressing, since we update the docs: how do we get the right transformation (e.g. how can a HPC expert know if there is an API-specific transformation exist or not ... even I usually don't know :) )? I have started to discuss this in #978 , but never did anything about it :)

[sergisiso]

And I think that section would be more than long enough to have its own chapter (and not part of "Psyclone transformations".) ... But I would prefer if it is listed in the "PSyclone transformations", with just a reference to the corresponding section in the Instrumentation chapter.

Just to be clear, I didn't mean to move them in the list of psyclone transformations, just to move the page location in the menu to the group of pages called "PSyclone transformations" that maybe also needs a more generic name:

I agree with your last point but lets discuss this on #978

[hiker]

Ah, I misunderstood. Then it all sounds great, thanks for designing this!!