mirror of
https://github.com/ManimCommunity/manim.git
synced 2026-06-22 10:01:47 +00:00
286f366a35* Improve section in docs about contributing to docs * Add note about doc build command depending on the OS * Improve section in docs about contributing to docs * Add note about doc build command depending on the OS * Fix wrong toctree path in docs/source/contributing/docs.rst
83 lines
2.8 KiB
ReStructuredText
83 lines
2.8 KiB
ReStructuredText
====================
|
|
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
|