Re-organize and consolidate Python examples and tutorials

[dbogdanov]

Consider reorganizing Python examples (*.py code examples) and tutorials (*.ipynb notebooks).

Currently both appear in two folders, src/examples/python and src/examples/tutorial, and this can create some confusion.

Consolidating into one folder is possibly a good approach. From the other side, there will be to many files and we could split into subfolders by topics.

[palonso]

I think that neither all the *.py files are examples nor all the *.ipynb are tutorials. But maybe the extension is already good enough for the division. What about src/examples/python and src/examples/python/notebooks. We could also rename the files as <type>_<title>.<ext> where type can be example or tutorial for consistency.

[palonso]

@dbogdanov should I go on and create a PR with this organization?

[dbogdanov]

I am reviewing the main notebook with examples and I am going to consolidate more examples from this tutorial. Let's hold on til I finish this.

I am thinking whether to split the examples by application already (e.g., melody detection, onsets, tempo, spectral shape) instead of having a single notebook. Having a single notebook is going to be very cluttered in the future as we are going to add even more examples.

[dbogdanov]

• Move all files from src/examples/tutorial to src/examples/python.

• Better naming for examples with respect to their application, for example:

  • example_clickdetector.ipynb --> example_audioproblems_clickdetector.ipynb @palonso

• Update links to notebooks that will be possibly broken, including from essentia-labs blog posts.

• Distinguish between Python examples and jupyter tutorials

  • Tutorials (name format: tutorial_category_task.ipynb, for example tutorial_rhythm_onsetdetection.ipynb) contain quality text description and code examples for particular tasks (e.g., feature extraction, beat tracking, onset detection, hum detection) grouped by categories (e.g., extractors, rhythm or audio problems)
  • Examples (name format: example_category_task.py) are python scripts that can be used to compute some features, minimally documented with comments in the code. We should ensure some minimum of consistency between the code in notebooks and examples.
  • Use tensorflow as a category.

• Create an index HTML (or rst) with links to each rendered tutorial (HTML) and original notebook (ipynb).

• Decide on code formatting standard to follow in all examples and tutorials (e.g., use 120-char line width for code).

• Refactor MusicBricks tutorials

• essentia_python_examples.html should be a landing page with an index of all tutorials and examples

[dbogdanov]

Started some work in the examples_updates branch.