Merge pull request #286 from ManimCommunity/sphinx-stuff

leotrs · web-flow · commit 4cc014cf365b · 2020-08-14T11:52:47.000-04:00
Sphinx setup: use autosummary to automatically generate module and class pages.
diff --git a/.gitignore b/.gitignore
@@ -56,6 +56,7 @@ coverage.xml
 # Sphinx documentation
 docs/_build/
 docs/build/
+docs/source/_autosummary/
 
 # PyBuilder
 target/
diff --git a/docs/source/_templates/autosummary/module.rst b/docs/source/_templates/autosummary/module.rst
@@ -0,0 +1,64 @@
+{{ fullname | escape | underline }}
+
+.. currentmodule:: {{ fullname }}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Module Attributes
+
+   .. autosummary::
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: Classes
+
+   .. autosummary::
+      :toctree: .
+      {% for class in classes %}
+        {{ class }}
+      {% endfor %}
+
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -31,8 +31,11 @@
     'sphinx.ext.autodoc',
     'sphinx_rtd_theme',
     'recommonmark',
+    'numpydoc',
 ]
 
+autosummary_generate = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
diff --git a/docs/source/config.rst b/docs/source/config.rst
diff --git a/docs/source/constants.rst b/docs/source/constants.rst
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -17,7 +17,7 @@ information here will make it easier for newcomers to get started using
 
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Documentation
 
    quickstart
diff --git a/docs/source/mobject.rst b/docs/source/mobject.rst
diff --git a/docs/source/reference.rst b/docs/source/reference.rst
@@ -3,12 +3,15 @@ Manim Reference
 
 This reference manual details functions, modules, and objects included in
 Manim, describing what they are and what they do.  For learning how to use
-Manim, see the quickstart and tutorial documents.
+Manim, see the :doc:`quickstart` and :doc:`tutorial` documents.
 
 
-.. toctree::
-   :maxdepth: 0
+.. currentmodule:: manim
 
-   mobject
+.. autosummary::
+   :toctree: _autosummary
+
+   container.container
+   mobject.mobject
    config
    constants
diff --git a/docs/source/tutorial.md b/docs/source/tutorial.md
@@ -1,3 +1,5 @@
+# Tutorial
+
 [NOTE:] this is some text I wrote that was originally meant to be part of the
 quickstart.  However, after some thought I've decided that it's probably a bit
 too much for the quickstart, as the quickstart document is supposed to showcase
diff --git a/manim/mobject/mobject.py b/manim/mobject/mobject.py
@@ -1,9 +1,5 @@
 """
-mobject.py
-----------
-
-Base classes for all MObjects.
-
+MObject: Base classes for all mathematical objects.
 """
 from functools import reduce
 import copy

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+# Tutorial`
	`2`	`+`
`1`	`3`	`[NOTE:] this is some text I wrote that was originally meant to be part of the`
`2`	`4`	`quickstart. However, after some thought I've decided that it's probably a bit`
`3`	`5`	`too much for the quickstart, as the quickstart document is supposed to showcase`