Skip to content

armgit / manim

Public Imported from GitHub
0

A community-maintained Python framework for creating mathematical animations.

Improve documentation section about contributing to docs (#3555)

Francisco Manríquez Novoa286f366a3584
diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst
index a9f7037d2..d47298572 100644
--- a/docs/source/contributing.rst
+++ b/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
diff --git a/docs/source/contributing/development.rst b/docs/source/contributing/development.rst
index b41592716..03de21642 100644
--- a/docs/source/contributing/development.rst
+++ b/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
diff --git a/docs/source/contributing/docs.rst b/docs/source/contributing/docs.rst
new file mode 100644
index 000000000..a8bb61c53
--- /dev/null
+++ b/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
diff --git a/docs/source/contributing/admonitions.rst b/docs/source/contributing/docs/admonitions.rst
similarity index 100%
rename from docs/source/contributing/admonitions.rst
rename to docs/source/contributing/docs/admonitions.rst
diff --git a/docs/source/contributing/docstrings.rst b/docs/source/contributing/docs/docstrings.rst
similarity index 100%
rename from docs/source/contributing/docstrings.rst
rename to docs/source/contributing/docs/docstrings.rst
diff --git a/docs/source/contributing/examples.rst b/docs/source/contributing/docs/examples.rst
similarity index 100%
rename from docs/source/contributing/examples.rst
rename to docs/source/contributing/docs/examples.rst
diff --git a/docs/source/contributing/references.rst b/docs/source/contributing/docs/references.rst
similarity index 100%
rename from docs/source/contributing/references.rst
rename to docs/source/contributing/docs/references.rst
diff --git a/docs/source/contributing/typings.rst b/docs/source/contributing/docs/typings.rst
similarity index 100%
rename from docs/source/contributing/typings.rst
rename to docs/source/contributing/docs/typings.rst
diff --git a/manim/utils/docbuild/__init__.py b/manim/utils/docbuild/__init__.py
index 967f61549..dee15b828 100644
--- a/manim/utils/docbuild/__init__.py
+++ b/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