Improve differential rotation documentation

[dstansby]

Following on from #3537, I have the following suggested improvements for the documentation for differential rotation:

• Move examples at the end of docs/code_ref/coordinates/rotatedsunframe.rst to their own files in examples/
• Add lots of intershpinx class links to docs/code_ref/coordinates/rotatedsunframe.rst
• Add a clear reference to the available methods (ie. formulae) that can be used for the rotation at the top of docs/code_ref/coordinates/rotatedsunframe.rst

[ayshih]

Move examples at the end of docs/code_ref/coordinates/rotatedsunframe.rst to their own files in examples/

While I'm fine with copying the examples out, I'm a little resistant to removing all of the examples. While they increase the length of the tutorial, I think they help in the teaching of why RotatedSunFrame is useful.

Add lots of intershpinx class links to docs/code_ref/coordinates/rotatedsunframe.rst

I didn't bother to intersphinx class links when there's an earlier mention of the class that already has the intersphinx link. It seems a bit absurd to me to intersphinx every mention, and it wouldn't be friendly to anyone who needs to step through the links. Do we have style guideline to use intersphinx in all possible situations?

I do note that I apparently screwed up the intersphinx link for sunpy.physics.differential_rotation.diff_rot, so that needs to be fixed.

Add a clear reference to the available methods (ie. formulae) that can be used for the rotation at the top of docs/code_ref/coordinates/rotatedsunframe.rst

I suggest adding a note right up top that this class makes use of the models within the diff_rot function, and have it the responsibility of that function's docstring to provide adequate details.

[dstansby]

While I'm fine with copying the examples out, I'm a little resistant to removing all of the examples. While they increase the length of the tutorial, I think they help in the teaching of why RotatedSunFrame is useful.

How about moving them to the examples and linking them at the end of the narrative docs? I think it would be good to have standalone examples in the gallery, and we want to avoid duplicating them.

I didn't bother to intersphinx class links when there's an earlier mention of the class that already has the intersphinx link. It seems a bit absurd to me to intersphinx every mention, and it wouldn't be friendly to anyone who needs to step through the links. Do we have style guideline to use intersphinx in all possible situations?

What do you mean by "needs to step through the links"? Surely there's no disadvantage to turning them all into links.

I suggest adding a note right up top that this class makes use of the models within the diff_rot function, and have it the responsibility of that function's docstring to provide adequate details.

Sounds good 👍

[Cadair]

Surely there's no disadvantage to turning them all into links.

Despite the fact we do it in a lot of places, repeating links is flagged as an accessibility concern for people using screen readers etc.

I think we should consider this more broadly than just here though. I tend to make them all links.

[dstansby]

Despite the fact we do it in a lot of places, repeating links is flagged as an accessibility concern for people using screen readers etc.

I did not know this, very good to know! I seem to remember you ran the website through an accessibility checker a while back on riot, did that ever get followed up in an issue?

[Cadair]

I opened one on the theme repo sunpy/sunpy-sphinx-theme#94 (I was initially thinking about our colour choices and lack of contrast) there are more issues with links etc though. I have opened #3767 to track the content side.