Manim: Should examples include import statements?

[kolibril13]

At the moment, examples from the docs don't have the import statements added.
I would prefer to write once that you need an import statement, and then not carry the import statement along to every other example. In my opinion, this would look tighter and we would have less redundancy, especially when we have chapters that will have like 10-20 examples.

[leotrs]

I'm of the opposite view. I like example code that I can copy & paste and have it work in no time. Someone is bound to copy&paste the code in the examples, and if they don't include the import statements they won't work.

[kolibril13]

I see.
Does sphinx support custom buttons?
An alternative idea:
we could add copy buttons next to each example with this sphinx extension:
https://sphinx-copybutton.readthedocs.io/en/latest/
Then we have the code shown in the examples without the import statement.
However, when you click on the copy button, it copies the code and appended to the import statement.

[leotrs]

I think that's a good alternative. There's still a bit of awkwardness if you see a chunk of code and copy it but when you paste it, it actually looks different (because the import statements have been added).

Honestly, in the vast majority of times the import statement will add only one line to the example. I don't think that's such a big deal, even if there are many examples per page. But I'm interested in what others have to say. @behackl @huguesdevimeux @naveen521kk ?

[kolibril13]

@leotrs : nitpicking: I think it would be two lines of code because there is one empty line in between. And e.g. the text examples will have about 20 examples which make 40 lines of code.

[leotrs]

40 lines of code in a webpage doesn't sound like a lot to me.

What _does_ sound like a lot to me is including 20 examples in a single page. But that's another discussion for another issue.

Again, we need more voices here to reach consensus. So imma stop responding until others do.

[naveen521kk]

For me personally, I will just copy paste using the button( in majority of sites) and run. So, I need example should contain import statement.

About copy button, it is ok, for me, to add import statement only in copy button and not to show it. But if we were to implement copy button we should also implement something like show raw file option along with copy button.

[behackl]

I feel that it would be pretty awkward if a copy/paste button would not copy the precise content of what is shown -- as a user, I might ask myself whether anything else was changed as well...

For the sake of simplicity, I would simply include the import statement in the examples.

[kolibril13]

ok, then I am fine with having import statements in the examples.
Next question:
Should they explicitly be added in the .rst files, or should they be added automatically when building the docs?
I would slightly prefer "explicitly be added"

[behackl]

Yes, I am very much against adding them automatically. If we want something to be displayed in the code block, then we should explicitly specify it. Everything else would cause confusion in the long run.

Adding them explicitly also gives us the option to just import things that are needed in a scene, if we decide to do so later on.

[leotrs]

They should be explicitly added.