New sections for the sphinx-example page

[kolibril13]

This pull request implements the folder structure that was discussed in #379.
The examples are currently only placeholder examples and will be properly extended in a future pull request, although they are already now related to the corresponding sections.

As this is a bigger change then #444, I think it's better to merge #444 first before merging this (With the assumption that you like these changes ;) ).
here is how it looks:

[leotrs]

The only comment I have is that all of the files inside the examples/ dir do not need to have "example" in their name. For example, I would suggest changing examples/text_examples.rst to just examples/text.rst. Note this generates shorter URLs as well.

[behackl]

We should probably also think about the relation between these examples and the reference manual.

Up to now, I mainly thought that examples illustrating a particular class or module should go in the corresponding docstrings so that they show up in the correct sections in the reference manual -- but I also really like the idea of having a more catalogue-like overview that makes it easy to see what manim can do without reading pages over pages of documentation.

I am not sure what is the best (long-term) approach here; what do you think?

[leotrs]

Yeah I agree. I think each class and method should should have at least one graphical example in the docstring. This example should be pretty bare bones and illustrate ONLY that particular feature.

Then, we can use the examples section for perhaps more advanced or complicated examples, using many features at once and showing how they relate to one another.

Regardless, it would be nice to be able to automatically link each other. For example, at the bottom of each class, we could add a section listing "examples using this class", and just give a list of links.

[kolibril13]

We should probably also think about the relation between these examples and the reference manual.

I am a huge fan of the catalogue-like overview, and for now, I want to improve that as a priority.
Having a link to the reference manual in the long term is something I also really like!
Maybe we can implement do this in a way similar to how the matplotlib people made this:
Yes, maybe we can do it the way this is also done in matplotlib:

• Here is the reference, that points to corresponding examples:
  https://matplotlib.org/api/_as_gen/matplotlib.pyplot.contourf.html
• And here is the example, that points to corresponding references:
  https://matplotlib.org/gallery/images_contours_and_fields/contourf_hatching.html

Yeah I agree. I think each class and method should have at least one graphical example in the docstring. This example should be pretty bare bones and illustrate ONLY that particular feature.

This would be additionally very nice to have! I think first having a gallery and bare bone examples in the docs is a good starting point, and afterwards, we can try to link them together

[behackl]

Yes, maybe we can do it the way this is also done in matplotlib:

• Here is the reference, that points to corresponding examples:
  https://matplotlib.org/api/_as_gen/matplotlib.pyplot.contourf.html
• And here is the example, that points to corresponding references:
  https://matplotlib.org/gallery/images_contours_and_fields/contourf_hatching.html

I really like this. Maybe there is a way to have the manim directive help us build something like that (semi-)automatically. I'll think about it a little; maybe we also open an issue for it.

[behackl]

Good stuff! I have some suggestions for minor imporvements, but overall I am satisfied; it will be good to have some sort of structure established.