Quick Start with the mne-project-template¶

This package serves as a skeleton package aiding at MNE compatible packages.

Creating your own mne contribution package¶

For illustration purposes we want to create a mne-foo project named mnefoo. Here is a table of the naming of this project and the project you will create:

	tis project	your resulting project
repo name	mne-project-template	mne-foo
package name	mnetemplate	mnefoo
import example	import mnetemplate	import mnefoo

1. Download and setup your repository¶

To create your package, you need to clone the mne-project-template repository and rename it to your convenience (i.e:mne-foo):

$ git clone https://github.com/mne-tools/mne-project-template.git mne-foo
$ cd mne-foo

Before to reinitialize your git repository, you need to replace the template information with you own. We provide you with a convenient script to speed up the process, but you can also do it manually.

1.1.1 bootstrap your mne project using a convenience script¶

Open your favorite editor and change PKG_NAME, PYTHON_NAME, and GH_NAME in mne_project_template_bootstrap.sh with your own information. Then run the bootsrap script:

$ bash  mne_project_template_bootstrap.sh

1.1.2 Update your project manually¶

Replace all occurrences of mnetemplate and mne-template with the name of you own contribution. You can find all the occurrences using the following command:

$ git grep mnetemplate
$ git grep mne-template

You can do this with your favorite editor or use the sed tool. In linux machine:

$ git grep -l 'mnetemplate' | xargs sed -i 's/mnetemplate/mnefoo/g'
$ git grep -l 'mne-template' | xargs sed -i 's/mne-template/mne-foo/g'

this is how to do it in Macosx machine:

$ git grep -l 'mnetemplate' | xargs sed -i '' -e 's/mnetemplate/mnefoo/g'
$ git grep -l 'mne-template' | xargs sed -i '' -e 's/mne-template/mne-foo/g'

Update the module directory name:

$ mv mnetemplate mnefoo

1.3 Remove history and convert it into a new project¶

To remove the history of the template package, you need to remove the .git directory:

$ rm -rf .git

Then, you need to initialize your new git repository:

$ git init
$ git add .
$ git commit -m 'Initial commit'

Finally, you create an online repository on GitHub and push your code online:

$ git remote add origin https://github.com/your_remote/mne-foo.git
$ git push origin master

2. Edit the documentation¶

The documentation is created using Sphinx. In addition, the examples are created using sphinx-gallery. Therefore, to generate locally the documentation, you are required to install the following packages:

$ pip install sphinx sphinx-gallery sphinx_rtd_theme matplotlib numpydoc pillow

The documentation is made of:

a home page, doc/index.rst;
an API documentation, doc/api.rst in which you should add all public objects for which the docstring should be exposed publicly.
a User Guide documentation, doc/user_guide.rst, containing the narrative documentation of your package, to give as much intuition as possible to your users.
examples which are created in the examples/ folder. Each example illustrates some usage of the package. the example file name should start by plot_*.py.

The documentation is built with the following commands:

$ cd doc
$ make html

3. Setup the continuous integration¶

The project template already contains configuration files of the continuous integration system. Basically, the following systems are set:

Travis CI is used to test the package in Linux. We provide you with an initial .travis.yml configuration file. So you only need to create a Travis account, activate own repository and trigger a build.
AppVeyor is used to test the package in Windows. You need to activate AppVeyor for your own repository. Refer to the AppVeyor documentation.
Circle CI is used to check if the documentation is generated properly. You need to activate Circle CI for your own repository. Refer to the Circle CI documentation.
ReadTheDocs is used to build and host the documentation. You need to activate ReadTheDocs for your own repository. Refer to the ReadTheDocs documentation.
CodeCov for tracking the code coverage of the package. You need to activate CodeCov for you own repository.
PEP8Speaks for automatically checking the PEP8 compliance of your project for each Pull Request.

Publish your package¶

You can make your package available through PyPi and conda-forge. Refer to the associated documentation to be able to upload your packages such that it will be installable with pip and conda. Once published, it will be possible to install your package with the following commands:

$ pip install mne-foo
$ conda install -c conda-forge mne-foo