deprecate MIDIAnimatorDocs repository, add docs to main

.gitignore

@@ -134,3 +134,6 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+
+# Sphinx documentation
+/docs/build/

docs/Makefile

@@ -0,0 +1,30 @@
+# 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
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+html: Makefile
+	sphinx-apidoc -f -o source/api ../MIDIAnimator
+	python3 make.py
+	$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+clean: Makefile
+	rm -f source/api/*.rst
+	@echo "Removing everything under source/api/*.rst"
+	$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/README.md

@@ -0,0 +1,27 @@
+# MIDIAnimator documentation
+
+Read the docs here: https://midianimatordocs.readthedocs.io/
+
+To build:
+
+1. Clone the repository `git clone https://github.com/imacj/MIDIAnimator.git` and `cd MIDIAnimator`.
+2. Run `pip install -r docs/requirements.txt`.
+3. Run `cd docs`.
+4. Run `make clean && make html` in the repository directory.
+5. Open `index.html` or run `open build/html/index.html` (for Mac users).
+
+Note: Instead of reStructuredText markdown files, this project uses MyST markdown files. For some basic information on MyST markdown, visit https://myst-parser.readthedocs.io/en/v0.15.1/sphinx/intro.html and https://jupyterbook.org/en/stable/reference/cheatsheet.html.
+
+**Please open a PR if you want to make changes to the docs.**
+
+<!--
+
+Useful commands:
+
+for building (in docs dir)
+make clean && make html
+
+for opening built html
+open build/html/index.html
+
+-->

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+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/make.py

@@ -0,0 +1,54 @@
+# because you cannot change how autodoc works, I wrote a custom stripper for the API docs that gets called before the docs are built.
+# This is a bit of a hack, but it works.
+
+import os
+
+for filename in os.listdir('source/api/'):
+    if ".libs." in filename\
+    or "MIDIAnimator.rst" == filename\
+    or "modules.rst" == filename:
+        os.remove(os.path.join('source/api/', filename))
+
+# now open the files up and edit them
+# the first line of the file will be the title of the module. We want to replace " package" with nothing, and "MIDIAnimator." with nothing. Still keep the old name (With the " package" replacement), as we want to check this against other lines
+# if the first two characters are "..", don't do anything (as this is an RST module), write the line and continue
+# if the line contains "Submodules" and the next line after that contains a dash, do not write either of those lines
+# if any line contains the first line of the file as described above + ".", replace it with nothing
+
+for filename in os.listdir('source/api/'):
+    if ".libs." in filename\
+    or "MIDIAnimator.rst" == filename\
+    or "modules.rst" == filename:
+        continue
+    with open(os.path.join('source/api/', filename), 'r') as f:
+        lines = f.readlines()
+
+    contains = False
+    title = ""
+    with open(os.path.join('source/api/', filename), 'w') as f:
+        for i, line in enumerate(lines):
+            if i == 0:
+                title = line.replace(" package", "")
+                f.write(title.replace("MIDIAnimator.", ""))
+                title = title.strip()
+                continue
+            if line.startswith(".."):
+                f.write(line)
+                continue
+            if "Submodules" in line:
+                if lines[lines.index(line) + 1].startswith("-"):
+                    contains = True
+                    continue
+
+            if contains:
+                contains = False
+                continue
+
+            if title in line:
+                line = line.replace(title + ".", "")
+            if " module" in line:
+                # replace with ".py"
+                line = line.replace(" module", ".py")
+            f.write(line)
+
+print("Sucessfully stripped signatures from API docs.")

docs/requirements.txt

@@ -0,0 +1,8 @@
+sphinx==4.5.0
+sphinx-rtd-theme==1.0.0
+
+myst-parser==0.17.2                 # via my-st
+mypy-extensions==0.4.3              # via my-st
+mdit-py-plugins==0.3.0              # via my-st
+fake-bpy-module-latest
+numpy

docs/source/conf.py

@@ -0,0 +1,68 @@
+# Configuration file for the Sphinx documentation builder.
+
+import os
+import sys
+import re
+
+sys.path.insert(0, os.path.abspath("../../"))
+from MIDIAnimator import bl_info
+
+# -- Project information
+
+project = 'MIDIAnimator'
+copyright = '2023, James Alt'
+author = 'James Alt'
+
+release = bl_info['name'].split(" ")[-1]
+version = bl_info['name'].split(" ")[-1]
+
+# -- General configuration
+
+extensions = [
+    'sphinx.ext.duration',
+    'sphinx.ext.doctest',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.intersphinx',
+    'myst_parser'
+]
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+    'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
+}
+intersphinx_disabled_domains = ['std']
+
+templates_path = ['_templates']
+
+# -- Options for HTML output
+
+html_theme = 'sphinx_rtd_theme'
+
+# -- Options for EPUB output
+epub_show_urls = 'footnote'
+
+autodoc_mock_imports = ["MIDIAnimator.libs", "ObjectShapeKey"]
+
+autodoc_class_signature = "separated"
+
+add_module_names = False
+
+exclude_patterns = ['api/modules.rst', 'api/MIDIAnimator.rst', 'api/MIDIAnimator.ui.rst']
+
+
+# thank you to https://github.com/sphinx-doc/sphinx/issues/4065#issuecomment-538535280
+def strip_signatures(app, what, name, obj, options, signature, return_annotation):
+    sig = None                                                                  
+    if signature is not None:                                                   
+        sig = re.sub('MIDIAnimator\.[^.]*\.', '', signature)                           
+
+    ret = None                                                                  
+    if return_annotation is not None:                                           
+        ret = re.sub('MIDIAnimator\.[^.]*\.', '', signature)                           
+
+    return sig, ret                                                             
+
+
+def setup(app):                                                                 
+    app.connect('autodoc-process-signature', strip_signatures)

docs/source/general/animation_types.md

@@ -0,0 +1,15 @@
+# Animation Types
+
+```{note}
+This section is under development. Check back later.
+```
+
+Evaluate animation. Takes an object with FCurves and duplicates it across the timeline. Parameters: Pass in a FCurve data object.
+
+Projectile animation. Pre-defined animation code that animates a projectile launching.
+
+Hi-Hat animation. Pre-defined animation code that animates how a hi-hat moves.
+
+Drumstick animation. Pre-defined animation code that animates how drumsticks move and feel. Procedural generation
+
+Custom animation. Defined by user, class and other parameters passed in via `addInstrument()`

docs/source/general/breakdown.md

@@ -0,0 +1,103 @@
+# Breakdown
+
+## How do we drive music animation?
+
+There are 2 different approaches to driving a music animation:
+
+1. FFT based approach- where you input an audio file (.wav, .mp3, etc) and have the visual elements react to the audio data. The audio data is filtered with steep inverse notch filters on selected frequencies. With the filtered data, you can then use the amplitude of the signal to drive animation parameters.
+
+2. Preactive approach using a MIDI file. A MIDI file is read in and broken down into its components. Animation curves get “copied” throughout the duration of the MIDI file, based on sets of parameters, typically determined by the notes in the MIDI file. The MIDI file determines when animations are being copied. This is the way MIDIAnimator works.
+
+## Process of creating a MIDI animation with MIDIAnimator (front/backend):
+MIDI files are broken down using the `MIDIFile()` class. `MIDIFile()` takes 1 parameter, which is the file where the MIDI file is stored. 
+
+`MIDIFile()` will create `MIDITrack()`, `MIDINote()` and `MIDIEvent()` objects based on the data inside of the MIDI file. 
+
+Structure of a `MIDIFile()` object:
+
+```
+MIDIFile:
+	file: string (where the MIDI file is stored)
+	tracks: list of MIDITrack objects
+
+	MIDITrack:
+		name: string
+		notes: list of MIDINote objects
+		control change: associative array that maps a control change number to a list of MIDIEvent values
+		aftertouch: list of MIDIEvent values
+		pitchwheel: list of MIDIEvent values
+
+		MIDINote:
+			channel: integer
+			noteNumber: integer
+			velocity: integer
+			timeOn: float, in seconds
+			timeOff: float, in seconds
+		
+		MIDIEvent:
+			channel: integer
+			value: float
+			time: float, in seconds
+```
+
+To get specific `MIDITrack` objects, use the `MIDIFile.findTrack()` method.
+
+To start adding instruments, instance a `MIDIAnimatorNode()` object
+
+* Use the `MIDIAnimatorNode.addInsturment()` method to add an instrument.
+    * Takes a `MIDITrack`, `bpy.types.Collection`.
+	* On instrument creation, `makeObjToFCurvesDict()` is called
+	    * Gets each Blender Object in a collection, gets their FCurves and creates `ObjectFCurves()` objects
+	* & `createNoteToBlenderObject()` is called
+	    *  Gets all Blender Objects in a collection, and creates `BlenderObject()` (a wrapper for a `bpy.types.Object`) objects, 
+        & adds their corresponding `ObjectFCurves` objects
+
+Call the `MIDIAnimatorNode.animate()` method to animate all instruments.
+
+* Given each instrument in the `MIDIAnimatorNode()` instruments list: 
+    * `preFrameLoop()` is called 
+        * `createFrameRanges()` is called
+        	* creates `FrameRange()` objects with the starting and ending frame for each note (based on its FCurve), and finds its corresponding Blender object.
+        * `preAnimate()` is called
+        	* `pass` by default.
+    * `animateFrames()` is called
+    	* `instrument.updateActiveObjectList()` gets called for every frame in the MIDI file
+    		* Removes and adds objects in the list of things being animated
+    	* `instrument.animate()` gets called for every frame in the MIDIFile
+    		* Looks at all objects in the active object list	
+    		* Loops over all objects, and applies the animation to them
+    * `postFrameLoop()` is called
+    	* Deletes all unnecessary information left over (clears all instance variables)
+
+## Dealing with overlapping animation:
+In Figure A, we are given a simple dampened oscillation function.
+
+<div style="text-align: center;">
+    <img alt="images/breakdown_figurea.png" src="https://raw.githubusercontent.com/jamesa08/MIDIAnimatorDocs/main/docs/images/breakdown_figurea.png">
+
+*Figure A, simple dampened oscillation*
+</div>
+
+If we were to animate Figure A using a simple MIDI file (2 notes, with the notes overlapping), it would look something like Figure B.
+
+However, there is a fundamental problem, as there is overlapping animation (denoted by the question mark in Figure B).
+
+<div style="text-align: center;">
+    <img alt="images/breakdown_figureb.png" src="https://raw.githubusercontent.com/jamesa08/MIDIAnimatorDocs/main/docs/images/breakdown_figureb.png">
+
+*Figure B, animation duplicated across timeline*
+</div>
+
+
+To deal with the overlapping animation, we can simply add the 2 animation curves together, shown in Figure C.
+
+<div style="text-align: center;">
+    <img alt="images/breakdown_figurec.png" src="https://raw.githubusercontent.com/jamesa08/MIDIAnimatorDocs/main/docs/images/breakdown_figurec.png">
+
+*Figure C, resulting animation curve*
+</div>
+
+
+### Problems with this approach:
+If the motion is not oscillating, the motion will be added together, in a result which is not desirable. 
+More techniques in dealing with overlapping animation will need to be researched. 

docs/source/general/future_plans.md

@@ -0,0 +1,3 @@
+# Future Plans
+
+- Future roadmap can be found [here](https://github.com/jamesa08/MIDIAnimator/projects).