Added documentation and docstrings (#19)

* Comment on the subcaptioning (#14)

* Comment on the subcaptioning

* Update README.md

Co-authored-by: Onur Solmaz <[email protected]>

* add another dependency of SoX needed for mp3 (#15)

Without the mp3 support, SoX breaks like here:
maximal/audio-waveform-php#3

* Create documentation (#13)

* Refactored

* Including suggestions by @peshto-ivanov

* Added example from Nour-eddine

* Minor

* Added doc files from Manim, added docstrings, wip

* Added more details

* Minor

* Minor

* Bumped version, updated shields

Co-authored-by: Pesho Ivanov <[email protected]>

.gitignore

@@ -7,4 +7,138 @@ media/
 tts-out/
 *.mp3
 media/
-scratch/
+scratch/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+*.log
+
+# Sphinx documentation
+docs/_build/
+docs/build/
+docs/source/_autosummary/
+docs/source/reference/
+docs/source/_build/
+docs/rendering_times.csv
+#i18n
+docs/i18n/gettext/.doctrees
+docs/i18n/**/*.mo
+docs/i18n/translatable.po
+docs/i18n/untranslatable.po
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+jupyter/
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# PyCharm
+/.idea/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+*.pyc
+*.bak
+.DS_Store
+
+.floo
+.flooignore
+.vscode
+.vs
+*.xml
+*.iml
+media
+.eggs/
+build/
+dist/
+
+/media_dir.txt
+# ^TODO: Remove the need for this with a proper config file

README.md

@@ -1,10 +1,15 @@
-# manim-voiceover
+# Manim Voiceover
 
-![Github Actions Status](https://github.com/ManimCommunity/manim-voiceover/workflows/Build/badge.svg)
-[![License](https://img.shields.io/github/license/ManimCommunity/manim-voiceover.svg?color=blue)](https://github.com/ManimCommunity/manim-voiceover/blob/main/LICENSE)
-[![](https://dcbadge.vercel.app/api/server/qY23bthHTY?style=flat)](https://manim.community/discord)
+<p>
+    <a href="https://github.com/ManimCommunity/manim-voiceover/workflows/Build/badge.svg"><img src="https://github.com/ManimCommunity/manim-voiceover/workflows/Build/badge.svg" alt="Github Actions Status"></a>
+    <a href="https://pypi.org/project/manim_voiceover/"><img src="https://img.shields.io/pypi/v/manim_voiceover.svg?style=flat&logo=pypi" alt="PyPI Latest Release"></a>
+    <a href="https://pepy.tech/project/manim_voiceover"><img src="https://pepy.tech/badge/manim_voiceover/month?" alt="Downloads"> </a>
+    <a href="https://manim_voiceover.readthedocs.io/en/latest/?badge=latest"><img src="https://readthedocs.org/projects/manim_voiceover/badge/?version=latest" alt="Documentation Status"></a>
+    <a href="https://github.com/ManimCommunity/manim-voiceover/blob/main/LICENSE"><img src="https://img.shields.io/github/license/ManimCommunity/manim-voiceover.svg?color=blue" alt="License"></a>
+    <a href="https://manim.community/discord"><img src="https://dcbadge.vercel.app/api/server/qY23bthHTY?style=flat" alt="Discord"></a>
+</p>
 
-`manim-voiceover` is a [Manim](https://manim.community) plugin for all things voiceover:
+Manim Voiceover is a [Manim](https://manim.community) plugin for all things voiceover:
 
 - Add voiceovers to Manim videos _directly in Python_ without having to use a video editor.
 - Develop an animation with an auto-generated AI voice without having to re-record and re-sync the audio.
@@ -20,92 +25,13 @@ Currently supported TTS services:
 - [gTTS](https://github.com/pndurette/gTTS/)
 - [pyttsx3](https://github.com/nateshmbhat/pyttsx3)
 
-## Installation
-
-Install from PyPI with the extras `azure` and `gtts`:
-
-```sh
-pip install manim-voiceover "manim-voiceover[azure]" "manim-voiceover[gtts]"
-```
-
-Check whether your installation works correctly:
-
-```sh
-manim -pql examples/gtts-example.py --disable_caching
-```
-
-The `--disable_caching` flag is required due to a Manim bug. TODO: Remove once the bug is fixed.
-
-[The example above](examples/gtts-example.py) uses [gTTS](https://github.com/pndurette/gTTS/) which calls the Google Translate API and therefore needs an internet connection to work. If it throws an error, there might be a problem with your internet connection or the Google Translate API.
-
-### Installing SoX
-
-`manim-voiceover` can make the output from speech synthesizers faster or slower using [SoX](http://sox.sourceforge.net/) (version 14.4.2 or higher is required).
-
-Install SoX on Mac with Homebrew:
-
-`brew install sox`
-
-Install SoX on Debian based distros:
-
-`sudo apt-get install sox`
-
-Or install [from source](https://sourceforge.net/projects/sox/files/sox/).
-
-## Basic Usage
+[Check out the documentation for more details.](https://voiceover.manim.community/)
 
-To use `manim-voiceover`, you simply import the `VoiceoverScene` class from the plugin
-
-```py
-from manim_voiceover import VoiceoverScene
-```
-
-You make sure your Scene classes inherit from `VoiceoverScene`:
-
-```py
-class MyAwesomeScene(VoiceoverScene):
-    def construct(self):
-        ...
-```
-
-`manim-voiceover` offers multiple text-to-speech engines, some proprietary and some free. A good one to start with is gTTS, which uses Google Translate's proprietary API. We found out that this is the best for beginners in terms of cross-platform compatibility---however it needs an internet connection.
-
-```py
-from manim_voiceover import VoiceoverScene
-from manim_voiceover.interfaces import GTTSService
-
-class MyAwesomeScene(VoiceoverScene):
-    def construct(self):
-        self.set_speech_service(GTTSService())
-```
-
-The logic for adding a voiceover is pretty simple. Wrap the animation inside a `with` block that calls `self.voiceover()`:
-
-```py
-with self.voiceover(text="This circle is drawn as I speak.") as tracker:
-    ... # animate whatever needs to be animated here
-```
-
-Manim will animate whatever is inside that with block. If the voiceover hasn't finished by the end of the animation, Manim will simply wait until it does. You can further use the `tracker` object for getting the total or remaining duration of the voiceover programmatically, which gives you finer control over the video:
-
-```py
-with self.voiceover(text="This circle is drawn as I speak.") as tracker:
-    self.play(Create(circle), run_time=tracker.duration)
-```
-
-Using with-blocks results in clean code, allows you to chain sentences back to back and also serve as a documentation of sorts, as the video is neatly compartmentalized according to whatever lines are spoken during the animations.
-
-See the [examples directory](./examples) for more examples. We recommend starting with the [gTTS example](https://github.com/ManimCommunity/manim-voiceover/blob/main/examples/gtts-example.py).
-
-## Configuring Azure
+## Installation
 
-The highest quality text-to-speech services available to the public is currently offered by Microsoft Azure. To use it, you need to create an Azure account.
+[Installation instruction in Manim Voiceover docs.](https://voiceover.manim.community/en/latest/installation.html)
 
-Then, you need to find out your subscription key and service region. Check out [Azure docs](https://docs.microsoft.com/en-us/azure/cognitive-services/speech-service/) for more details.
+## Get started
 
-Create a file called `.env` that contains your authentication information in the same directory where you call Manim.
+[Check out the docs for getting started with Manim Voiceover.](https://voiceover.manim.community/en/latest/quickstart.html)
 
-```sh
-AZURE_SUBSCRIPTION_KEY="..."
-AZURE_SERVICE_REGION="..."
-```

docs/Makefile

@@ -0,0 +1,33 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+
+# Path base is the source directory
+SOURCEDIR     = .
+BUILDDIR      = ../build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@(cd source; $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O))
+
+.PHONY: help Makefile i18n
+
+# All the code is executed as if everything was launched in one shell.
+.ONESHELL:
+# Like make clean but also remove files generated by autosummary and
+# rendered videos.
+cleanall: clean
+	@rm source/reference/*
+	@rm -rf source/media
+	@rm -f rendering_times.csv
+i18n:
+	@(cd source; $(SPHINXBUILD) -M gettext "$(SOURCEDIR)" ../i18n/ -t skip-manim $(SPHINXOPTS) $(O);cd ../i18n;bash stripUntranslatable.sh)
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@(cd source; $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O))

docs/make.bat

@@ -0,0 +1,37 @@
+@ECHO OFF
+
+pushd %~dp0\source
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+
+REM The paths are taken from the source directory
+set SOURCEDIR=.
+set BUILDDIR=..\build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

@@ -0,0 +1,5 @@
+sphinx==4.1.2
+furo
+recommonmark>=0.5.0
+sphinx-copybutton
+sphinxext-opengraph

docs/rtd-requirements.txt

@@ -0,0 +1,2 @@
+jupyterlab
+sphinxcontrib-programoutput