[DOC] Adding doc folder and tightening makefile recipes for checking style

.flake8

@@ -0,0 +1,26 @@
+
+[flake8]
+max-line-length = 115
+
+ignore =
+    # these rules don't play well with black
+    # whitespace before :
+    E203
+    # line break before binary operator
+    W503
+    E241,E305,W504,W605,E731
+
+
+exclude =
+    .venv
+    .git
+    __pycache__
+    docs/build
+    dist
+    .mypy_cache
+    __init__.py
+
+per-file-ignores =
+    # __init__.py files are allowed to have unused imports and lines-too-long
+    */__init__.py:F401
+    */**/**/__init__.py:F401,E501

.github/workflows/unit_tests.yml

@@ -31,7 +31,7 @@ jobs:
           pip install --upgrade --upgrade-strategy eager -r requirements.txt
           pip install --upgrade --upgrade-strategy eager -r requirements_testing.txt
       - name: Run style & documentation tests
-        run: make pep
+        run: make run-checks
 
   # Run installation tests
   build:

.gitignore

@@ -26,6 +26,9 @@ share/python-wheels/
 .installed.cfg
 *.egg
 MANIFEST
+_build/
+generated/
+auto_examples/
 
 # PyInstaller
 #  Usually these files are written by a python script from a template

CONTRIBUTING.md

@@ -0,0 +1,177 @@
+# Contributing
+
+Thanks for considering contributing! Please read this document to learn the various ways you can contribute to this project and how to go about doing it.
+
+## Bug reports and feature requests
+
+### Did you find a bug?
+
+First, do [a quick search](https://github.com/mne-tools/mne-icalabel/issues) to see whether your issue has already been reported.
+If your issue has already been reported, please comment on the existing issue.
+
+Otherwise, open [a new GitHub issue](https://github.com/mne-tools/mne-icalabel/issues).  Be sure to include a clear title
+and description.  The description should include as much relevant information as possible.  The description should
+explain how to reproduce the erroneous behavior as well as the behavior you expect to see.  Ideally you would include a
+code sample or an executable test case demonstrating the expected behavior.
+
+### Do you have a suggestion for an enhancement or new feature?
+
+We use GitHub issues to track feature requests. Before you create an feature request:
+
+* Make sure you have a clear idea of the enhancement you would like. If you have a vague idea, consider discussing
+it first on a GitHub issue.
+* Check the documentation to make sure your feature does not already exist.
+* Do [a quick search](https://github.com/mne-tools/mne-icalabel/issues) to see whether your feature has already been suggested.
+
+When creating your request, please:
+
+* Provide a clear title and description.
+* Explain why the enhancement would be useful. It may be helpful to highlight the feature in other libraries.
+* Include code examples to demonstrate how the enhancement would be used.
+
+## Making a pull request
+
+When you're ready to contribute code to address an open issue, please follow these guidelines to help us be able to review your pull request (PR) quickly.
+
+1. **Initial setup** (only do this once)
+
+    <details><summary>Expand details 👇</summary><br/>
+
+    If you haven't already done so, please [fork](https://help.github.com/en/enterprise/2.13/user/articles/fork-a-repo) this repository on GitHub.
+
+    Then clone your fork locally with
+
+        git clone https://github.com/USERNAME/mne-icalabel.git
+
+    or 
+
+        git clone [email protected]:USERNAME/mne-icalabel.git
+
+    At this point the local clone of your fork only knows that it came from *your* repo, github.com/USERNAME/mne-icalabel.git, but doesn't know anything the *main* repo, [https://github.com/mne-tools/mne-icalabel.git](https://github.com/mne-tools/mne-icalabel). You can see this by running
+
+        git remote -v
+
+    which will output something like this:
+
+        origin https://github.com/USERNAME/mne-icalabel.git (fetch)
+        origin https://github.com/USERNAME/mne-icalabel.git (push)
+
+    This means that your local clone can only track changes from your fork, but not from the main repo, and so you won't be able to keep your fork up-to-date with the main repo over time. Therefore you'll need to add another "remote" to your clone that points to [https://github.com/mne-tools/mne-icalabel.git](https://github.com/mne-tools/mne-icalabel). To do this, run the following:
+
+        git remote add upstream https://github.com/mne-tools/mne-icalabel.git
+
+    Now if you do `git remote -v` again, you'll see
+
+        origin https://github.com/USERNAME/mne-icalabel.git (fetch)
+        origin https://github.com/USERNAME/mne-icalabel.git (push)
+        upstream https://github.com/mne-tools/mne-icalabel.git (fetch)
+        upstream https://github.com/mne-tools/mne-icalabel.git (push)
+
+    Finally, you'll need to create a Python 3 virtual environment suitable for working on this project. There a number of tools out there that making working with virtual environments easier.
+    The most direct way is with the [`venv` module](https://docs.python.org/3.7/library/venv.html) in the standard library, but if you're new to Python or you don't already have a recent Python 3 version installed on your machine,
+    we recommend [Miniconda](https://docs.conda.io/en/latest/miniconda.html).
+
+    On Mac, for example, you can install Miniconda with [Homebrew](https://brew.sh/):
+
+        brew install miniconda
+
+    Then you can create and activate a new Python environment by running:
+
+        conda create -n mne-icalabel python=3.9
+        conda activate mne-icalabel
+
+    Once your virtual environment is activated, you can install your local clone in "editable mode" with
+
+        pip install -U pip setuptools wheel
+        pip install -e .[dev]
+
+    The "editable mode" comes from the `-e` argument to `pip`, and essential just creates a symbolic link from the site-packages directory of your virtual environment to the source code in your local clone. That way any changes you make will be immediately reflected in your virtual environment.
+
+    </details>
+
+2. **Ensure your fork is up-to-date**
+
+    <details><summary>Expand details 👇</summary><br/>
+
+    Once you've added an "upstream" remote pointing to [https://github.com/allenai/python-package-temlate.git](https://github.com/mne-tools/mne-icalabel), keeping your fork up-to-date is easy:
+
+        git checkout main  # if not already on main
+        git pull --rebase upstream main
+        git push
+
+    </details>
+
+3. **Create a new branch to work on your fix or enhancement**
+
+    <details><summary>Expand details 👇</summary><br/>
+
+    Committing directly to the main branch of your fork is not recommended. It will be easier to keep your fork clean if you work on a separate branch for each contribution you intend to make.
+
+    You can create a new branch with
+
+        # replace BRANCH with whatever name you want to give it
+        git checkout -b BRANCH
+        git push -u origin BRANCH
+
+    </details>
+
+4. **Test your changes**
+
+    <details><summary>Expand details 👇</summary><br/>
+
+    Our continuous integration (CI) testing runs [a number of checks](https://github.com/mne-tools/mne-icalabel/actions) for each pull request on [GitHub Actions](https://github.com/features/actions). You can run most of these tests locally, which is something you should do *before* opening a PR to help speed up the review process and make it easier for us.
+
+    For convenience you can run a check for all style components necessary:
+
+        make run-checks
+
+    This will run isort, black, flake8, mypy, check-manifest, and pydocstyle on the entire repository. Please fix your errors if you see any.
+
+    First, you should run [`isort`](https://github.com/PyCQA/isort) and [`black`](https://github.com/psf/black) to make sure you code is formatted consistently.
+    Many IDEs support code formatters as plugins, so you may be able to setup isort and black to run automatically every time you save.
+    For example, [`black.vim`](https://github.com/psf/black/tree/master/plugin) will give you this functionality in Vim. But both `isort` and `black` are also easy to run directly from the command line.
+    Just run this from the root of your clone:
+
+        isort .
+        black .
+
+    Our CI also uses [`flake8`](https://github.com/mne-tools/mne-icalabel/tree/main/tests) to lint the code base and [`mypy`](http://mypy-lang.org/) for type-checking. You should run both of these next with
+
+        flake8 .
+
+    and
+
+        mypy .
+
+    We also strive to maintain high test coverage, so most contributions should include additions to [the unit tests](https://github.com/mne-tools/mne-icalabel/tree/main/tests). These tests are run with [`pytest`](https://docs.pytest.org/en/latest/), which you can use to locally run any test modules that you've added or changed.
+
+    For example, if you've fixed a bug in `causal_networkx/a/b.py`, you can run the tests specific to that module with
+
+        pytest -v tests/a/b_test.py
+
+    Our CI will automatically check that test coverage stays above a certain threshold (around 90%). To check the coverage locally in this example, you could run
+
+        pytest -v --cov causal_networkx.a.b tests/a/b_test.py
+
+    If your contribution involves additions to any public part of the API, we require that you write docstrings
+    for each function, method, class, or module that you add.
+    See the [Writing docstrings](#writing-docstrings) section below for details on the syntax.
+    You should test to make sure the API documentation can build without errors by running
+
+        make docs
+
+    If the build fails, it's most likely due to small formatting issues. If the error message isn't clear, feel free to comment on this in your pull request.
+
+    And finally, please update the [CHANGELOG](https://github.com/mne-tools/mne-icalabel/blob/main/CHANGELOG.md) with notes on your contribution in the "Unreleased" section at the top.
+
+    After all of the above checks have passed, you can now open [a new GitHub pull request](https://github.com/mne-tools/mne-icalabel/pulls).
+    Make sure you have a clear description of the problem and the solution, and include a link to relevant issues.
+
+    We look forward to reviewing your PR!
+
+    </details>
+
+### Writing docstrings
+
+We use [Sphinx](https://www.sphinx-doc.org/en/master/index.html) to build our API docs, which automatically parses all docstrings
+of public classes and methods. All docstrings should adhere to the [Numpy styling convention](https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html).

LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2022, MNE
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

MANIFEST.in

@@ -1,16 +1,25 @@
 include *.png
 include *.txt
+include *.md
 include Makefile
+
+# examples
 recursive-include examples *.py
 recursive-include examples *.txt
+
+# main files
 recursive-include mne_icalabel *.pt
 recursive-include mne_icalabel *.py
-recursive-include test_data *.mat
 
+exclude .circleci/config.yml
+exclude .flake8
+
+recursive-exclude doc *
+
+# exclude all data files
+recursive-exclude mne_icalabel *.txt
 recursive-exclude mne_icalabel *.fif
 recursive-exclude mne_icalabel *.m
-
-exclude .circleci/config.yml
 recursive-exclude mne_icalabel *.fdt
 recursive-exclude mne_icalabel *.mat
 recursive-exclude mne_icalabel *.set

Makefile

@@ -91,7 +91,7 @@ flake:
 black:
 	@if command -v black > /dev/null; then \
 		echo "Running black"; \
-		black --check mne_icalabel examples; \
+		black mne_icalabel examples; \
 	else \
 		echo "black not found, please install it!"; \
 		exit 1; \
@@ -114,11 +114,30 @@ check-manifest:
 check-readme:
 	python setup.py check --restructuredtext --strict
 
+isort:
+	@if command -v isort > /dev/null; then \
+		echo "Running isort"; \
+		isort mne_icalabel examples; \
+	else \
+		echo "isort not found, please install it!"; \
+		exit 1; \
+	fi;
+	@echo "isort passed"
+
 pep:
 	@$(MAKE) -k black pydocstyle codespell-error check-manifest
 
 docstyle: pydocstyle
 
+run-checks:
+	isort --check .
+	black --check mne_icalabel examples
+	flake8 .
+	mypy ./mne_icalabel
+	@$(MAKE) pydocstyle
+	check-manifest
+	@$(MAKE) codespell-error
+
 build-doc:
 	@echo "Building documentation"
 	make -C doc/ clean

README.md

@@ -19,22 +19,23 @@ This package aims at automating that process conforming to the popular MNE-Pytho
 TBD. Add example code for how this works.
 
 # Documentation
-TBD
+[Stable version](https://mne.tools/mne-icalabel/stable/index.html) documentation.
+[Dev version](https://mne.tools/mne-icalabel/dev/index.html) documentation.
 
 # Installation
 
 To get the latest code using [git](https://git-scm.com/), open a terminal and type:
 
-    git clone git://github.com/jacobf18/iclabel-python.git
+    git clone git://github.com/mne-tools/mne-icalabel.git
     cd iclabel-python
     pip install -e .    
 
 or one can install directly using pip
 
-    pip install --user -U https://api.github.com/repos/jacobf18/iclabel-python/zipball/main
+    pip install --user -U https://api.github.com/repos/mne-tools/mne-icalabel/zipball/main
 
 Alternatively, you can also download a
-`zip file of the latest development version <https://github.com/mne-tools/mne-connectivity/archive/main.zip>`__.
+`zip file of the latest development version <https://github.com/mne-tools/mne-icalabel/archive/main.zip>`__.
 
 ## Converting MatConvNet to PyTorch