Improve documentation section about contributing to docs (#3555)

* 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

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

@@ -147,7 +147,7 @@ Develop your contribution
 
    Update the docstrings (the text in triple quotation marks) of any functions
    or classes you change and include them with any new functions you add.
-   See the :doc:`documentation guide <docstrings>` for more information about how we
+   See the :doc:`documentation guide <docs/docstrings>` for more information about how we
    prefer our code to be documented. The content of the docstrings will be
    rendered in the :doc:`reference manual <../reference>`.
 
@@ -245,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,83 @@
+====================
+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

manim/utils/docbuild/__init__.py

@@ -4,11 +4,7 @@ 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/docstrings`
--   :doc:`/contributing/references`
--   :doc:`/contributing/examples`
--   :doc:`/contributing/typings`
--   :doc:`/contributing/admonitions`
+-   :doc:`/contributing/docs`
 
 .. autosummary::
    :toctree: ../reference