[Docs FR] Add inset example

[KronosTheLate]

Currently, searching for inset in the Makie docs returns nothing. If we wonder how to make an inset plot, we are left with googling forum discussions like this one and try to work it out.

It would be fantastic if there was a page in the documentation showing how to create an inset figure, which also explained what you need to be careful with when doing it (such as z-ordering and transparency).

[sashansamarajeewa]

Hello,

I am a MSc in Computer Science student from the University of Stuttgart, Germany. I am currently following the course, Simulation Software Engineering (SSE).

For this course we need to select an open-source simulation software and make a small contribution to get familiar with it. I am interested in Makie and looking for a suitable topic to work on. There are no clear expectations as to what this contribution should be. It could be either a new feature, a tutorial, a documentation or a bug fix.

I am a newbie to the field of simulation softwares but eager to learn and to contribute something useful. Is it possible to work on this "good first issue" if it is still relevant?

If yes, I would like your input and guidance on how to get started so that I can give a meaningful contribution.

If no, could you please point me to something else you would recommend that I can contribute to in Makie?

Thank You

[ffreyer]

Sure you can work on this. More documentation is always good to have.

I think this issue comes in two parts. The first part would just be about how to make an inset Axis - with some code that is easy to copy and modify. There should be enough information about this on discourse. In fact, you can probably just summarize the thread that's linked here.

If you're new to git and/or github, I would recommend you figure that stuff out at this point. I.e. forking the Makie repository, creating a branch where you commit your changes, uploading that to your fork and creating a (draft) pull request to this repository. The tutorial should be a new file in https://github.com/MakieOrg/Makie.jl/tree/master/docs/src/tutorials and needs to be included in https://github.com/MakieOrg/Makie.jl/blob/master/docs/makedocs.jl. The pull request includes a docs preview so you can also use it to check that everything is working as intended.

The second part would be adding related information, e.g:

• pixel units vs relative units for Axis size and placement (the layouting tutorials probably explain this)
• z ordering (probably useful to skim Axis.jl and maybe lineaxis.jl for translate!() calls to see what range of z values it occupies)
• How to mark the section that the inset axis shows (Iirc there is a discourse thread on this)
• How to add an inset Axis on top of other axis types (Iirc there is a discourse thread for LScene or Axis3, but this may also not work well enough to be worth including)

Hopefully these are easy questions to answer after going through a few threads on discourse. But even if that's not the case or you run out of time, just having a basic tutorial on inset Axis would be a meaningful contribution.

[jkrumbiegel]

I think we should probably just add a function inset_axis! that does the basic setup automatically. That function would also need some docs but in general that will be a better user experience than having complex docs on the manual setup.

The function signature would be something like inset_axis!(ax::Axis, xs, ys) and you could set a space keyword to decide if the rectangle should be in relative or screen or data coordinates.

[sashansamarajeewa]

Thank you for the inputs. I will try to come up with a PR to address this.

[sashansamarajeewa]

Please refer to the potential PR for closing the issue.