chore(docs): improving the docs a bit more (#116)

* chore(docs): improving the docs a bit more

This adds some useful extensions, links, and add. information.

* fix(deps): update lockfiles no-cache

Author: jeertmans

docs/source/conf.py

@@ -16,7 +16,9 @@
 
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
+    "sphinxext.opengraph",
     "sphinx_click",
     "myst_parser",
     "sphinx_copybutton",
@@ -31,3 +33,29 @@
 
 html_theme = "furo"
 html_static_path = ["_static"]
+
+html_theme_options = {
+    "footer_icons": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/jeertmans/manim-slides",
+            "html": """
+                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
+                    <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
+                </svg>
+            """,
+            "class": "",
+        },
+    ],
+    "source_repository": "https://github.com/jeertmans/manim-slides/",
+    "source_branch": "main",
+    "source_directory": "docs/source/",
+}
+
+## -- Intersphinx mapping
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "manim": ("https://docs.manim.community/en/stable/", None),
+    "manimlib": ("https://3b1b.github.io/manim/", None),
+}

docs/source/reference/examples.md

@@ -2,7 +2,28 @@
 
 Contents of `example.py`.
 
-Do not forget to import Manim Slides and Manim or ManimGL.
+Do not forget to import Manim Slides and Manim or ManimGL:
+
+```python
+from manim import *
+from manim_slides import Slide, ThreeDSlide
+```
+
+or
+
+```python
+from manimlib import *
+from manim_slides import Slide, ThreeDSlide
+```
+
+Then, each presentation, named `SCENE`, was generated with those two commands:
+
+```bash
+manim example.py SCENE # or manimgl example SCENE
+manim-slides convert SCENE -ccontrols=true
+```
+
+where `-ccontrols=true` indicates that we want to display the blue navigation arrows.
 
 ## Basic Example
 

manim_slides/slide.py

@@ -27,7 +27,7 @@ def reverse_video_file(src: str, dst: str) -> None:
 
 class Slide(Scene):  # type:ignore
     """
-    Inherits from :class:`manim.Scene` or :class:`manimlib.Scene` and provide necessary tools for slides rendering.
+    Inherits from :class:`manim.scene.scene.Scene` or :class:`manimlib.scene.scene.Scene` and provide necessary tools for slides rendering.
     """
 
     def __init__(
@@ -229,7 +229,7 @@ def render(self, *args: Any, **kwargs: Any) -> None:
 
 class ThreeDSlide(Slide, ThreeDScene):  # type: ignore
     """
-    Inherits from :class:`Slide` and :class:`manim.ThreeDScene` or :class:`manimlib.ThreeDScene` and provide necessary tools for slides rendering.
+    Inherits from :class:`Slide` and :class:`manim.scene.three_d_scene.ThreeDScene` or :class:`manimlib.scene.three_d_scene.ThreeDScene` and provide necessary tools for slides rendering.
 
     .. note:: ManimGL does not need ThreeDScene for 3D rendering in recent versions, see `example.py`.
     """

poetry.lock

@@ -88,6 +88,7 @@ myst-parser = "^0.18.1"
 sphinx = "^5.3.0"
 sphinx-click = "^4.4.0"
 sphinx-copybutton = "^0.5.1"
+sphinxext-opengraph = "^0.7.5"
 
 [tool.poetry.group.test.dependencies]
 manim = "^0.17.0"