Add a how-to guide section

[wtbarnes]

Please rebase and merge. Do not squash merge.

Fixes #6909
Fixes #5427

I've converted one entry from the example gallery to a how-to guide which I thought was a fairly uncontroversial example. I'd like to limit this PR to just adding the section/general structure and then leave a larger restructuring of other content to how-to guides to other PRs. A debate on what in the example gallery should be moved here would tie this up indefinitely.

I'd mostly like to decide on naming, formatting, high-level text and general wording for the descriptions of the sections here. Once we have this merged, we can start reorganizing more asynchronously.

[dstansby]

Two suggestions:

For the map stuff, I've left inline comments. Essentially I think having code that loads a map into a variable at the top, then using that variable in the code snippets below would be a bit clearer.

I think some words could be saved by splitting the table into different sections. For e.g. the map section, there could be a "Maps" title at the top, and then the text could change like:

• "create a map from a FITS file" > "load from a FITS file"
• "save a map to a FITS file" > "save to a FITS file"
• "get a quicklook summary of a map" > "get a quicklook"

removing all the "a map" bits would make it easier to read IMO

[wtbarnes]

Essentially I think having code that loads a map into a variable at the top, then using that variable in the code snippets below would be a bit clearer.

I initially avoided this because I was directly linking to the docstring, but since I'm constructing the links manually anyway, I think this does make more sense.

I think some words could be saved by splitting the table into different sections.

I disagree. I think the table should be as simple as possible and as short as possible, particularly since these code snippets are not tested. I'm worried that if it starts increasing in complexity and length, we'll just be duplicating the API docs and the table will lose its purpose.

[dstansby]

👍 - I still definietely thing there are words to be cut down for brevity/readability, but I'm happy to bikeshed that in a future PR instead of here.

[wtbarnes]

👍 - I still definietely thing there are words to be cut down for brevity/readability, but I'm happy to bikeshed that in a future PR instead of here.

Agreed. I made a pass at making it a bit less wordy and avoiding repetition.

[dstansby]

👏

[wtbarnes]

🎉 We now have spaces for all four diataxis sections!