Contributing Guide🔗

Tracker🔗

Contributions in all forms to this wiki are welcome. This wiki is hosted and build on GitHub. The issue tracker can be used to propose changes, additions and report issues and solutions found when working with MEG data from our site.

Pull Requests🔗

If comfortable with git and collaborative development, pull request to the repository are welcome. The wiki is organized as a python project with a sphinx documentation. The documentation, used to generate the website HTML pages, is written in reStructuredText format in the doc folder. For instance, doc/meg-session.rst contains the content of the MEG session page.

In a pull request, the automatic workflows will build the documentation and check for conformity. Any warnings and errors during the build process must be resolved before the pull request can be merged.

Building the documentation locally🔗

To confirm that the documentation build without warning, it is possible to build the documentation locally. After cloning the repository, the project and its dependencies can be installed in a python environment with:

$ pip install -e path/to/meg-wiki[all]

Additionally, pre-commit hooks are available to check for common errors before committing changes.

$ pip install pre-commit
$ pre-commit install

The documentation can be build from the meg-wiki/doc folder with make commands:

  • make html to build the entire website.

  • make html-noplot to build the website without running the tutorials.

  • make clean to remove the generated and build files.

  • make view to open the build website in the default browser.

  • make linkcheck followed by make linkcheck-grep to test for broken URLs.

Tutorials🔗

Python-based tutorials and code snippet are executed using sphinx-gallery. The tutorials are written in a plain python .py file in the folder meg-wiki/tutorials. The file naming must follow the pattern dd_*.py with dd corresponding to 2 digits used to order the tutorials. The # %% jupyter syntax is used to denote separate sections.