Docs needs structure rework

[Alexboiboi]

Related issues

#580

Scope

The current docs are actually pretty nice but let us agree that some structural rework has to be done here ^^

I am just going to enumerate some issues I see (I'll probably edit this post along the way):

• The current intro is very long
• Most intro topics a redundantly explained in the FUNCTIONALITY section.
• The absolute must of python loop avoidance should almost be on the landing page^^. We could have a section named smth like Make magpylib great again, no just kidding^^, more like Important caveats or just Reach full performance. In this section we can expose the benefits of magpylib vs FEM in the first place and then show the caveats with python loops and finish with the core package use.
• It lacks some reference on general python knowledge. From people getting in touch via github it is striking that quite some people don't master python or even know python at all. This should be more prominent in the docs. Maybe add Absolute beginner's guide section-> also recommend going through numpy's "Absolute beginner's guide" as magpylib internally functions a lot like numpy. A magpylib user should definitely get the grasp of numpy's functioning, again because of the loop caveat.
• I am missing the substructure for Graphics, Collections and Complex-Shapes. Why have removed it?
• When sharing docs links. The internal docs structure becomes visible and is kinda ugly. e.g.: https://magpylib.readthedocs.io/en/latest/_pages/page_01_introduction.html#intro-field-computation -> _pages/page_01

A few suggestions:

• take some inspiration out of numpy docs and myst-nb docs
• rename the FUNCTIONALITY section into USER GUIDE
• remove the intro entirely and dispatch its content in the USER GUIDE
• remove the CONTENT section. Some part can lie on the top level.

Dear community members, please share your thoughts ;)