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.rstindex 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 outContributing can be confusing, so here are a few guides:.. toctree::- :maxdepth: 2+ :maxdepth: 3contributing/development- contributing/docstrings- contributing/references- contributing/examples- contributing/typings- contributing/admonitions+ contributing/docscontributing/testingcontributing/performancecontributing/internationalizationdiff --git a/docs/source/contributing/development.rst b/docs/source/contributing/development.rstindex b41592716..03de21642 100644--- a/docs/source/contributing/development.rst+++ b/docs/source/contributing/development.rst@@ -147,7 +147,7 @@ Develop your contributionUpdate the docstrings (the text in triple quotation marks) of any functionsor 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 weprefer our code to be documented. The content of the docstrings will berendered 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 documentationyou added looks as you intended. You can build the documentation locallyby 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 forfeedback and iterate over any requested changes. You will likely be asked todiff --git a/docs/source/contributing/docs.rst b/docs/source/contributing/docs.rstnew file mode 100644index 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/typingsdiff --git a/docs/source/contributing/admonitions.rst b/docs/source/contributing/docs/admonitions.rstsimilarity index 100%rename from docs/source/contributing/admonitions.rstrename to docs/source/contributing/docs/admonitions.rstdiff --git a/docs/source/contributing/docstrings.rst b/docs/source/contributing/docs/docstrings.rstsimilarity index 100%rename from docs/source/contributing/docstrings.rstrename to docs/source/contributing/docs/docstrings.rstdiff --git a/docs/source/contributing/examples.rst b/docs/source/contributing/docs/examples.rstsimilarity index 100%rename from docs/source/contributing/examples.rstrename to docs/source/contributing/docs/examples.rstdiff --git a/docs/source/contributing/references.rst b/docs/source/contributing/docs/references.rstsimilarity index 100%rename from docs/source/contributing/references.rstrename to docs/source/contributing/docs/references.rstdiff --git a/docs/source/contributing/typings.rst b/docs/source/contributing/docs/typings.rstsimilarity index 100%rename from docs/source/contributing/typings.rstrename to docs/source/contributing/docs/typings.rstdiff --git a/manim/utils/docbuild/__init__.py b/manim/utils/docbuild/__init__.pyindex 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