Overhaul of documentation system (AcademySoftwareFoundation#312)

Summary: This change merges the entire OTIO wiki into the main OTIO repo. This lets us version the documentation along with the code, and makes it easier to publish static documentation (e.g. to readthedocs.org).

Details:

* Remove old documentation files

They are out of date, and the generated ones for the API should not be checked into source control. By creating them at build time you can run tests against the documentation and ensure that the examples in the documentation are up to date with the code that has been written.

Additionally, I'm moving the doc folder over to docs in order to keep parity with the plurality of 'tests'

* Add MANIFEST.in file

By adding a Manifest file, we control what will get built into the final package so that we're not adding files that don't need to go into the package on pypi. This will be run in the tox step that will be added in a commit that is coming up which will build out a temporary distribution and check that the results in the output package file match up with what we've defined in here. I'd also like to exclude the examples folder, but if I exclude it, everything in my virtualenv goes nuts and breaks and I can't figure out why and I don't feel like putting more time into that.

* Migrate Wiki over to tutorials and generate all API documentation

Migrating the Wiki was actually the easy part. By adding the recommonmark sphinx plugin, I could just download the Wiki from Github and use the Markdown files that existed, with slight changes to fit into the sphinx-rtd-theme. NOTE that this isn't done or perfect, but it's 95% of the work done. So you might be wondering why one would want to move the wiki over to documentation in the project and the answer is simple - the wiki is not version controlled in alignment with the package and releases of the package.

Building the documentation along with the version of the package allows the user to see changes and explanation alongside whatever version they're using, while the Wiki does not. Yes, they will have to generate it, but with the integration of tox (coming in a separate commit), we make that so much easier on the user with the command `tox -e build-docs`. This practice also helps encourage developers to keep updating their documentation and it's worked great at the last few studios I've worked at and implemented it at.

* Add tox to dev dependencies and add tox file

Since this is a new dependency, you'll have to rerun the install command with `pip install -e .[dev]`, deactivate your virtualenv, and then source it again. After that, you only have to run `tox` when you're sourced inside of your virtualenv to run all the tests, and you can run `tox -e build-docs` to build the documentation. This is not finished yet, I plan to add a couple more steps to the tox script in a coming commit, but for the purpose of running tests and building documentation, this works.

If a tox environment ever gets funky, you can run `tox -r` to rebuild the environments. I have only ever had to do that once.

* Update file documentation to build API docs properly

Since I added the ability for Sphinx to build ALL of the API documentation, there were docstrings that were never touched by the build stuff that was set up previously, and thus had issues that prevented documentation from building. This was a rather annoying chore to have to go through, and I should not have messed with any code at all, it should have only been docstrings getting messed with (minus the import statements in tests). I would appreciate you all looking at this and making sure, though.

* Documentation formatting updates

Adding images, formatting, fixing tables, making links work.

* Add ReadTheDocs configuration file

* Add apidoc to Sphinx building and move module tree in index

* Cleanup for conf.py file and adding documentation link to README

* Flake8 cleanup and update manifest file

* Remove pip installs from Travis, change pep8 to pycodestyle, add to tox

* Test moving coverage call to tox

* Change py.test command to module being called from python for Travis

* Add tox-travis plugin to travis file

* Fix coverage on Travis

* Actually fix coverage on Travis and in Tox

* Add coverage dependency to travis pip installation

Didn't think about the fact that it should be needed outside of the virtualenvs that Tox creats

* Minor fixes to new doc system (#3)

* Fixed indentation issue in doc string.

* Changed Makefile doc-html target to run new tox -e build-docs.

* Put lambda idiom back the way it was.

* Adjust version string in conf.py for documentation

Author: boredstiff

.gitignore

@@ -8,3 +8,7 @@ dist*
 
 # Pycharm metadata
 .idea/
+
+# These files are generated, don't put them into source control
+docs/api
+.tox

.readthedocs.yml

@@ -0,0 +1,6 @@
+build:
+    image: latest
+
+python:
+    version: 3.6
+    setup_py_install: true

.travis.yml

@@ -19,16 +19,12 @@ before_install:
     - wget -qO /tmp/${PYAAF} "https://github.com/markreidvfx/pyaaf/releases/download/v1.0.0/${PYAAF}"
 
 install:
-    - pip install pep8 pyflakes flake8 coverage
-    - pip install Pillow  # only needed for some contrib adapters
-    - pip install --upgrade pip setuptools wheel
+    # tox-travis installs tox and also makes working with travis better.
+    - pip install tox-travis coverage
     - pip install /tmp/${PYAAF}
 
 script:
-    - make lint
-    - make test
-    # Build coverage which will get uploaded to codecov
-    - make coverage
+    - tox
 
 after_success:
     # Documentation for codecov uploader

MANIFEST.in

@@ -0,0 +1,17 @@
+include README.md CHANGELOG.md LICENSE.txt NOTICE.txt
+recursive-include examples *
+
+recursive-exclude docs *
+prune docs
+exclude .readthedocs.yml
+exclude .codecov.yml
+exclude .gitlab-ci.yml
+exclude .travis.yml
+exclude *.pdf
+exclude CODE_OF_CONDUCT.md
+exclude CONTRIBUTING.md
+exclude opentimelineio_contrib/adapters/Makefile
+exclude Makefile
+
+recursive-exclude opentimelineio_contrib/adapters/tests *
+recursive-exclude tests *

Makefile

@@ -20,7 +20,7 @@ $(ccblue)	pip install -e .[dev]$(newline)$(ccend)
 endef
 
 COV_PROG := $(shell command -v coverage 2> /dev/null)
-PEP8_PROG := $(shell command -v pep8 2> /dev/null)
+PYCODESTYLE_PROG := $(shell command -v pycodestyle 2> /dev/null)
 PYFLAKES_PROG := $(shell command -v pyflakes 2> /dev/null)
 FLAKE8_PROG := $(shell command -v flake8 2> /dev/null)
 # AUTOPEP8_PROG := $(shell command -v autopep8 2> /dev/null)
@@ -82,8 +82,8 @@ clean:
 
 # run the codebase through flake8.  pep8 and pyflakes are called by flake8.
 lint:
-ifndef PEP8_PROG
-	$(error $(newline)$(ccred)pep8 is not available on $$PATH please see:$(newline)$(ccend)\
+ifndef PYCODESTYLE_PROG
+	$(error $(newline)$(ccred)pycodestyle is not available on $$PATH please see:$(newline)$(ccend)\
 	$(ccblue)	https://pypi.python.org/pypi/pep8#installation$(newline)$(ccend)\
 	$(dev_deps_message))
 endif
@@ -102,4 +102,4 @@ endif
 
 # generate documentation in html
 doc-html:
-	@make -C doc html | sed 's#build/#doc/build/#g'
+	@tox -e build-docs

README.md

@@ -36,6 +36,10 @@ You can provide adapters for your video editing tool or pipeline as needed.
 Each adapter allows for import/export between that proprietary tool and the
 OpenTimelineIO format.
 
+Documentation
+--------------
+[Documentation is available on ReadTheDocs](https://opentimelineio.readthedocs.io/)
+
 Use Cases
 ---------