diff --git a/docs/community/contribute.md b/docs/community/contribute.md index 0ed9d5da0b84..9e9601856fb9 100644 --- a/docs/community/contribute.md +++ b/docs/community/contribute.md @@ -13,6 +13,7 @@ After your patch has been merged, remember to add your name to [CONTRIBUTORS.md] * [Document](#documents) * [Test Cases](#test-cases) * [Examples](#examples) +* [Tutorials](#tutorials) * [Core Library](#core-library) * [Python Package](#python-package) * [R Package](#r-package) @@ -110,6 +111,10 @@ It's fine to force a push to your own fork, as long as only your commits are cha tutorials that use MXNet, please tell us and we'll add a link to them in the examples on GitHub. +## Tutorials + +Want to contribute an MXNet tutorial? To get started, download the [tutorial template](https://github.com/dmlc/mxnet/tree/master/example/MXNetTutorialTemplate.ipynb). + ## Core Library - We follow the Google C++ Style Guide for C++ code. diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md index e92080265245..73af3a7d259e 100644 --- a/docs/tutorials/index.md +++ b/docs/tutorials/index.md @@ -148,6 +148,9 @@ Applications that use traditional methods to model classification and regression - [Handwritten Digit Classification](http://mxnet.io/tutorials/scala/mnist.html) *A simple example of classifying handwritten digits from the MNIST dataset using a multilayer perceptron.* +## Contributing Tutorials + +Want to contribute an MXNet tutorial? To get started, download the [tutorial template](https://github.com/dmlc/mxnet/tree/master/example/MXNetTutorialTemplate.ipynb). ## Other Resources - [MXNet Code Examples](https://github.com/dmlc/mxnet/tree/master/example) diff --git a/example/MXNetTutorialTemplate.ipynb b/example/MXNetTutorialTemplate.ipynb new file mode 100644 index 000000000000..2ec9b8562a46 --- /dev/null +++ b/example/MXNetTutorialTemplate.ipynb @@ -0,0 +1,436 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Tutorial Title" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "A brief introduction to the tutorial that describes:\n", + "\n", + "- The problem that that the tutorial addresses\n", + "- Who the intended audience is\n", + "- The expected experience level of that audience with a concept or tool \n", + "- Which environment/language it runs in \n", + "\n", + "If there is another similar tutorial that's more appropriate for another audience, direct the reader there with a linked reference." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## How to Use This Tutorial" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "A brief explanation of how the reader can use the tutorial. Can the reader copy each code snippet into a Python or other environment? Or can the reader run before or after reading through the explanations to understand how the code works?" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "You can use this tutorial by *insert method(s) here*. \n", + "\n", + "A bulleted list of the tasks the reader will accomplish and skills he or she will learn. Begin each list item with a noun (Learn, Create, Use, etc.).\n", + "\n", + "You will accomplish the following:\n", + "\n", + "- First task or skill\n", + "- Second task or skill\n", + "- X task or skill" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Prerequisites" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Provide a *complete* list of the software, hardware, knowledge, and skills required to be successful using the tutorial. For each item, link the item to installation instructions, specs, or skill development tools, as appropriate. If good installation instructions aren't available for required software, start the tutorial with instructions for installing it." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To complete this tutorial, you need:\n", + "\n", + "- [MXNet](//http://mxnet.io/get_started/setup.html#overview)\n", + "- [Language](http://)\n", + "- [Tool](http://)\n", + "- Familiarity with concept or tool" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## The Data" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Provide a link to where the data is hosted and explain how to download it. If it requires more than two steps, use a numbered list." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "You can download the data used in this tutorial from the [Site Name](http://) site. To download the data:\n", + "\n", + "1. At the prompt, type:\n", + "\n", + " ``command``\n", + "\n", + "2. Second task.\n", + "\n", + "3. Last task." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Briefly describe key aspects of the data. If there are two or more aspects of the data that require involved discussion, use subheads (### ). To include a graphic, introduce it with a brief description and use the image linking tool to include it. Store the graphic in GitHub and use the following format: \"screen. You do not need to provide a title for your graphics. " + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The data *add description here. (optional)*" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## (Optional) Concept or Component Name" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "If concepts or components need further introduction, include this section. If there are two or more aspects of the concept or component that require involved discussion, use subheads (### Concept or Sub-component Name)." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Prepare the Data" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "If appropriate, summarize the tasks required to prepare the data, defining and explaining key concepts." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To prepare the data, *provide explanation here.*" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Use a numbered procedure to explain how to prepare the data. Add code snippets or blocks that show the code that the user must type or that is used for this task in the Jupyter Notebook. To include code snippets, precede each line of code with four spaces and two tick marks. Always introduce input or output with a description or context or result, followed by a colon." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To prepare the data:\n", + "\n", + "1.\n", + "\n", + "2.\n", + "\n", + "3." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "If there are any aspects of data preparation that require elaboration, add it here." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Create the Model" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "If appropriate, summarize the tasks required to create the model, defining and explaining key concepts." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To create the model, *provide explanation here.*" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Use a numbered procedure to explain how to create the data. Add code snippets or blocks that show the code that the user must type or that is used for this task in the Jupyter Notebook. To include code snippets, precede each line of code with four spaces and two tick marks. Always introduce input or output with a description or context or result, followed by a colon." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To create the model:\n", + "\n", + "1.\n", + "\n", + "2.\n", + "\n", + "3." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "If there are any aspects of model creation that require elaboration, add it here." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Fit the Model" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "If appropriate, summarize the tasks required to create the model, defining and explaining key concepts." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To fit the model, *provide explanation here.*" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Use a numbered procedure to explain how to fit the model. Add code snippets or blocks that show the code that the user must type or that is used for this task in the Jupyter Notebook. To include code snippets, precede each line of code with four spaces and two tick marks. Always introduce input or output with a description or context or result, followed by a colon." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To fit the model:\n", + "\n", + "1.\n", + "\n", + "2.\n", + "\n", + "3." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "If there are any aspects of model fitting that require elaboration, add it here." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Evaluate the Model" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "If appropriate, summarize the tasks required to evaluate the model, defining and explaining key concepts." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To evaluate the model, *provide explanation here.*" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Use a numbered procedure to explain how to evaluate the model. Add code snippets or blocks that show the code that the user must type or that is used for this task in the Jupyter Notebook. To include code snippets, precede each line of code with four spaces and two tick marks. Always introduce input or output with a description or context or result, followed by a colon." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To evaluate the model:\n", + "\n", + "1.\n", + "\n", + "2.\n", + "\n", + "3." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "If there are any aspects of model evaluation that require elaboration, add it here." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## (Optional) Additional Tasks" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "If appropriate, summarize the tasks required to perform the task, defining and explaining key concepts." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To *perform the task*, *provide explanation here.*" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Use a numbered procedure to explain how to perform the task. Add code snippets or blocks that show the code that the user must type or that is used for this task in the Jupyter Notebook. To include code snippets, precede each line of code with four spaces and two tick marks. Always introduce input or output with a description or context or result, followed by a colon." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To *perform the task*:\n", + "\n", + "1.\n", + "\n", + "2.\n", + "\n", + "3." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "If there are any aspects of model evaluation that require elaboration, add it here." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Summary" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Briefly describe the end result of the tutorial and how the user can use it or modify it to customize it." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Next Steps" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Provide a bulleted list of other documents, tools, or tutorials that further explain the concepts discussed in this tutorial or build on this tutorial. Start each list item with a brief description of a user task followed by the title of the destination site or topic that is formatted as a link." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "- For more information on *topic*, see [Site Name](http://).\n", + "- To learn more about using *tool or task*, see [Topic Title](http://).\n", + "- To experiment with *service*, *tool*, or *object*, see [Site Name](http://).\n", + "- For a more advanced tutorial on *subject*, see [Tutorial Title](http://)." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 2", + "language": "python", + "name": "python2" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 2 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython2", + "version": "2.7.12" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/example/README.md b/example/README.md index 7552f3fe101b..ecaeece40151 100644 --- a/example/README.md +++ b/example/README.md @@ -20,7 +20,7 @@ This page contains a curated list of awesome MXnet examples, tutorials and blogs ## Contributing -If you want to contribute to this list and the examples, please open a new pull request. +If you want to contribute to this list and the examples, please open a new pull request. To get started, download the [tutorial template](https://github.com/dmlc/mxnet/tree/master/example/MXNetTutorialTemplate.ipynb). ##List of examples