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

docs/source/conf.py

@@ -16,7 +16,9 @@ author = "Jérome Eertmans"
 
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
+    "sphinxext.opengraph",
     "sphinx_click",
     "myst_parser",
     "sphinx_copybutton",
@@ -31,3 +33,29 @@ exclude_patterns = []
 
 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 @@ class Slide(Scene):  # type:ignore
 
 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

@@ -1333,6 +1333,17 @@ python-versions = ">=3.5"
 lint = ["docutils-stubs", "flake8", "mypy"]
 test = ["pytest"]
 
+[[package]]
+name = "sphinxext-opengraph"
+version = "0.7.5"
+description = "Sphinx Extension to enable OGP support"
+category = "dev"
+optional = false
+python-versions = ">=3.7"
+
+[package.dependencies]
+sphinx = ">=4.0"
+
 [[package]]
 name = "srt"
 version = "3.5.2"
@@ -1499,7 +1510,7 @@ testing = ["flake8 (<5)", "func-timeout", "jaraco.functools", "jaraco.itertools"
 [metadata]
 lock-version = "1.1"
 python-versions = ">=3.8.1,<3.12"
-content-hash = "c3931f97423e6cf1082a0144b675da951151869c357f33a44a3bce06fd0b6520"
+content-hash = "0f342939336f7eac6af6ebf0ac4bc9922777f12b0b4c7718f869dad73860c64d"
 
 [metadata.files]
 alabaster = [
@@ -2750,6 +2761,10 @@ sphinxcontrib-serializinghtml = [
     {file = "sphinxcontrib-serializinghtml-1.1.5.tar.gz", hash = "sha256:aa5f6de5dfdf809ef505c4895e51ef5c9eac17d0f287933eb49ec495280b6952"},
     {file = "sphinxcontrib_serializinghtml-1.1.5-py2.py3-none-any.whl", hash = "sha256:352a9a00ae864471d3a7ead8d7d79f5fc0b57e8b3f95e9867eb9eb28999b92fd"},
 ]
+sphinxext-opengraph = [
+    {file = "sphinxext-opengraph-0.7.5.tar.gz", hash = "sha256:caf061fb3bea8d8f2228f7a1d55cb8f6809f2b5c806bf3600e21ce1a3cf906d1"},
+    {file = "sphinxext_opengraph-0.7.5-py3-none-any.whl", hash = "sha256:d7fcf48b5d6477292492c0c7da6ddc469e3657159952e2a0a0df074f54aad99e"},
+]
 srt = [
     {file = "srt-3.5.2.tar.gz", hash = "sha256:7aa4ad5ce4126d3f53b3e7bc4edaa86653d0378bf1c0b1ab8c59f5ab41384450"},
 ]

pyproject.toml

@@ -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"