A community-maintained Python framework for creating mathematical animations.
Added Guide to Contribute Examples from GitHub Wiki to Documentation (#1387)
Nikhil Garudafccce24a9b98
diff --git a/docs/source/contributing/documentation.rst b/docs/source/contributing/documentation.rstindex 42d22d66e..8d7e118a4 100644--- a/docs/source/contributing/documentation.rst+++ b/docs/source/contributing/documentation.rst@@ -3,8 +3,88 @@ Adding Documentation====================When submitting a new class through a PR, or any changes in general,-there should be documentation where possible. Here are the guidelines-for writing it.+there should be documentation where possible. Here are our guidelines+for writing documentation.++Guidelines for examples+-----------------------++Everybody is welcome to contribute examples to the documentation. Since straightforward examples are a great resource for quickly learning manim, here are some guidelines.++What makes a great example+--------------------------++.. note::++ As soon as a new version of manim is released, the documentation will be a snapshot of that version. Examples contributed after the release will only be shown in the latest documentation.++* Examples should be ready to copy and paste for use.++* Examples should be brief yet still easy to understand.++* Examples don't require the ``from manim import *`` statement, this will be added automatically when the docs are built.++* There should be a balance of animated and non-animated examples.++- As manim makes animations, we can include lots of animated examples; however, our RTD has a maximum 15 minutes to build. Animated examples should only be used when necessary, as last frame examples render faster.++- Lots of examples (e.g. size of a plot-axis, setting opacities, making texts, etc.) will also work as images. It is a lot more convenient to see the end product immediately instead of waiting for an animation to reveal it.++* Please ensure the examples run on the current master when you contribute an example.++How examples are structured+---------------------------++* Examples can be organized into chapters and subchapters.++- When you create examples, the beginning example chapter should focus on only one functionality. When the functionality is simple, multiple ideas can be illustrated under a single example.++- As soon as simple functionalities are explained, the chapter may include more complex examples which build on the simpler ideas.++Writing examples+~~~~~~~~~~~~~~~~++When you want to add/edit examples, they can be found in the ``docs/source/`` directory, or directly in the manim source code (e.g. ``manim/mobject/mobject.py``). The examples are written in+``rst`` format and use the manim directive (see :mod:`~.manim_directive` ), ``.. manim::``. Every example is in its own block, and looks like this:++.. code:: rst++ Formulas+ ========++ .. manim:: Formula1+ :save_last_frame:++ class Formula1(Scene):+ def construct(self):+ t = MathTex(r"\int_a^b f'(x) dx = f(b) - f(a)")+ self.add(t)+ self.wait(1)++In the building process of the docs, all ``rst`` files are scanned, and the+manim directive (``.. manim::``) blocks are identified as scenes that will be run+by the current version of manim.+Here is the syntax:++* ``.. manim:: [SCENE_NAME]`` has no indentation and ``SCENE_NAME`` refers to the name of the class below.++* The flags are followed in the next line (no blank line here!), with the indention level of one tab.++All possible flags can be found at :mod:`~.manim_directive`.++In the example above, the ``Formula1`` following ``.. manim::`` is the scene+that the directive expects to render; thus, in the python code, the class+has the same name: ``class Formula1(Scene)``.++.. note::++ Sometimes, when you reload an example in your browser, it has still the old+ website somewhere in its cache. If this is the case, delete the website cache,+ or open a new incognito tab in your browser, then the latest docs+ should be shown.+ **Only for locally built documentation:** If this still doesn't work, you may need+ to delete the contents of ``docs/source/references`` before rebuilding+ the documentation.Formatting and Running Tests----------------------------@@ -91,7 +171,7 @@ Example:See an example on list item 4.-.. NOTE::+.. note::When documenting varargs (args and kwargs), make sure todocument them by listing the possible types of each value specified,@@ -140,9 +220,10 @@ See an example on list item 4.# python code here-**NOTE: Also, if this is a video- or animation-related change, please-try to add an example GIF or video if possible for demonstration-purposes.**+.. note::+ Also, if this is a video- or animation-related change, please+ try to add an example GIF or video if possible for demonstration+ purposes.Make sure to be as explicit as possible in your documentation. We allwant the users to have an easier time using this library.@@ -152,7 +233,8 @@ Example:.. code:: pydef my_function(thing, other, name, *, d, test=45): # typings are optional for now- """My cool function. Builds and modifies an :class:`EpicClassInThisFile` instance with the given parameters.+ """My cool function. Builds and modifies an :class:`EpicClassInThisFile` instance with the given+ parameters.Parameters----------