====================
Adding Documentation
====================

Building the documentation
--------------------------

When you clone the Manim repository from GitHub, you can access the
``docs/`` folder which contains the necessary files to build the
documentation.

To build the docs locally, open a CLI, enter the ``docs/`` folder with the
``cd`` command and execute the following depending on your OS:

-   Windows: ``./make.bat html``
-   macOS and Linux: ``make html``

The first time you build the docs, the process will take several
minutes because it needs to generate all the ``.rst`` (reST:
reStructured Text) files from scratch by reading and parsing all the
Manim content. The process becomes much shorter the next time, as it
rebuilds only the parts which have changed.


Sphinx library and extensions
-----------------------------

Manim uses `Sphinx <https://www.sphinx-doc.org>`_ for building the
docs. It also makes use of Sphinx extensions such as:

-   `Autodoc: <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>`_
    imports Manim's Python source code, extracts its docstrings and
    generates documentation from them.
-   `Autosummary: <https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html>`_
    a complement to Autodoc which adds a special directive ``autosummary``,
    used in Manim to automatically document classes, methods,
    attributes, functions, module-level variables and exceptions.
    Autosummary makes use of `Jinja templates <https://jinja.palletsprojects.com/templates/>`_,
    which Manim defines for autosummarizing classes and modules
    inside ``docs/source/_templates/``.
-   `Graphviz extension for Sphinx: <https://www.sphinx-doc.org/en/master/usage/extensions/graphviz.html>`_
    embeds graphs generated by the `Graphviz <https://graphviz.org/>`_
    module, which must be installed in order to render the
    inheritance diagrams in the :doc:`/reference`.
-   `Napoleon: <https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html>`_
    enables Sphinx to read Google style docstrings and, in
    particular for Manim, `NumPy style docstrings <https://numpydoc.readthedocs.io/en/latest/format.html>`_
    - see :doc:`docs/docstrings` for more information.


Sphinx theme
------------

The theme used for this website is `Furo <https://sphinx-themes.org/sample-sites/furo/>`_.


Custom Sphinx directives
------------------------

Manim implements **custom directives** for use with Autodoc and Autosummary, which
are defined in :mod:`~.docbuild`:

.. currentmodule:: manim.utils.docbuild

.. autosummary::

    :toctree: ../reference
    autoaliasattr_directive
    autocolor_directive
    manim_directive


Index
-----

.. toctree::
   :maxdepth: 2

   docs/admonitions
   docs/docstrings
   docs/examples
   docs/references
   docs/typings
   docs/types
