Improve documentation section about contributing to docs

docs/source/contributing.rst

@@ -38,14 +38,10 @@ To get an overview of what our community is currently working on, check out
 Contributing can be confusing, so here are a few guides:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
 
    contributing/development
-   contributing/docstrings
-   contributing/references
-   contributing/examples
-   contributing/typings
-   contributing/admonitions
+   contributing/docs
    contributing/testing
    contributing/performance
    contributing/internationalization

docs/source/contributing/development.rst

@@ -159,6 +159,8 @@ Develop your contribution
 As far as development on your local machine goes, these are the main steps you
 should follow.
 
+.. _polishing-changes-and-submitting-a-pull-request:
+
 Polishing Changes and Submitting a Pull Request
 -----------------------------------------------
 
@@ -243,7 +245,8 @@ sticks to our coding conventions.
   a look at the built HTML files to see whether the formatting of the documentation
   you added looks as you intended. You can build the documentation locally
   by running ``make html`` from the ``docs`` directory. Make sure you have `Graphviz <https://graphviz.org/>`_
-  installed locally in order to build the inheritance diagrams.
+  installed locally in order to build the inheritance diagrams. See :doc:`docs` for
+  more information.
 
 Finally, if the pipeline passes and you are satisfied with your changes: wait for
 feedback and iterate over any requested changes. You will likely be asked to

docs/source/contributing/docs.rst

@@ -0,0 +1,80 @@
+====================
+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) 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 :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/source/reference_index/utilities_misc.rst

@@ -9,23 +9,25 @@ Module Index
 .. autosummary::
    :toctree: ../reference
 
-   constants
    ~utils.bezier
    ~utils.color
    ~utils.commands
    ~utils.config_ops
-   ~utils.deprecation
+   constants
    ~utils.debug
+   ~utils.deprecation
    ~utils.docbuild
    ~utils.hashing
-   ~utils.ipython_magic
    ~utils.images
+   ~utils.ipython_magic
    ~utils.iterables
    ~utils.paths
    ~utils.rate_functions
    ~utils.simple_functions
    ~utils.sounds
    ~utils.space_ops
+   ~utils.testing
    ~utils.tex
-   ~utils.tex_templates
    ~utils.tex_file_writing
+   ~utils.tex_templates
+   typing

manim/utils/docbuild/__init__.py

@@ -0,0 +1,17 @@
+"""Utilities for building the Manim documentation.
+
+For more information about the Manim documentation building, see:
+
+-   :doc:`/contributing/development`, specifically the ``Documentation``
+    bullet point under :ref:`polishing-changes-and-submitting-a-pull-request`
+-   :doc:`/contributing/docs`
+
+.. autosummary::
+   :toctree: ../reference
+
+   autoaliasattr_directive
+   autocolor_directive
+   manim_directive
+   module_parsing
+
+"""

manim/utils/testing/__init__.py

@@ -0,0 +1,17 @@
+"""Utilities for Manim tests using `pytest <https://pytest.org>`_.
+
+For more information about Manim testing, see:
+
+-   :doc:`/contributing/development`, specifically the ``Tests`` bullet
+    point under :ref:`polishing-changes-and-submitting-a-pull-request`
+-   :doc:`/contributing/testing`
+
+.. autosummary::
+
+   :toctree: ../reference
+   frames_comparison
+   _frames_testers
+   _show_diff
+   _test_class_makers
+
+"""