Skip to content

Latest commit

 

History

History
336 lines (244 loc) · 13.3 KB

CONTRIBUTING.md

File metadata and controls

336 lines (244 loc) · 13.3 KB
Raw

CONTRIBUTING

Open Issue on GitHub 🎫

If you would like to contribute, make bug report/fix, participate in language translation work or if you have any other queries please do not hesitate to open an issue using one of the issue templates

Making a PR 🖋️

If you want to contribute with your ideas and suggestions please make a pull request by following the Template format to the repository of the book. The more suggestions and ideas are shared and contributed by the members of the community, this book will be a more beneficial source for the community.

What, Where 🔎

  • All the text for each chapter of the book lives inside the folder ./brainhack_book directory.

  • All figures associated with the chapters are stored in and linked from the ./brainhack_book/static directory.

  • Everything else is in the brainhack_book/ directory.

Configuration ⚙️

  • The table of contents (TOC) defines the order of chapters as they appear in the book. To change the TOC, please edit ./brainhack_book/_toc.yml with correct information of filenames and their relative locations in this repository. Documentation on controlling the TOC structure can be found on the jupyter book website.

  • Same applies for more general configuration using ./brainhack_book/_config.yml. Documentation on configuring book settings can be found on the jupyter book website.

Deploying 🚀

The site is built and deployed automatically using a Github action, from the main branch.

Viewing the brainhack_book 👀

Before start, you might need to have these listed below ready.

  • A recent version of Python (Python) to work on the book and view it locally. If you do not have Python on your computer, we warmly recommend the install instruction from the datalad handbook.

If you are using an earlier version of Windows than Windows 10, you might want to check the install instruction for Python and bash from this page from the neurohackademy.

  • Note the install procedure below requires you to have git installed on your computer.

  • If you are a Windows user for Unix commands and build functions to work properly you might either need

Fork the Brainhack Jupyter Book repository to your Github account 🔱

Click on the ‘Fork’ button near the top of the page. This creates a copy of the code under your account on GitHub. For more details on how to fork a repository see this guide.

This is now your own unique copy of the Brainhack Jupyter Book. Changes here won't affect anyone else's work, so it's a safe space to explore edits to the code!

Make sure to keep your fork up to date with the upstream repository, otherwise, you can end up with lots of dreaded merge conflicts.

Clone your forked Brainhack Jupyter Book repository to your machine/computer. 🔽

While you can edit files directly on Github, sometimes the changes you want to make will be complex and you will want to use a text editor that you have installed on your local machine/computer. (One great text editor is vscode). In order to work on the code locally, you must clone your forked repository.

git clone [email protected]:YOURUSERNAME/brainhack_jupyter_book.git
cd brainhack_book

To keep up with the changes in the Brainhack Jupyter Book repository, add the Brainhack Jupyter Book repository as a remote to your locally cloned repository.

The first time you try to sync your fork, you may have to set the upstream branch:

git remote add upstream https://github.com/brainhack_jupyter_book/brainhack_jupyter_book.git
git remote -v # Making sure the upstream repo is listed.

Make sure to keep your fork up to date with the upstream repository. For example, to update your main branch on your local cloned repository:

git fetch upstream
git checkout main
git merge upstream/main

Synchronize your main branch with the upstream main branch: 🔄

git checkout main
git pull upstream main

You can then create a new branch to work on an issue. Using a new branch allows you to follow the standard GitHub workflow when making changes. This guide provides a useful overview of this workflow. Please keep the name of your branch short and self-explanatory.

git checkout -b MYBRANCH

Installing Dependencies in a virtual environment ⬆️

For the requirements please have a look at our requirements.txt

Virtual environments are a great way of isolating project-related dependencies from your system-level Python installation.

For more details on virtual environments using a tool like venv in Python see here.

You can also use Conda that acts both as a way to manage your environments and install packages. For more info about Conda, you can check this page of the The Turing Way project.

To use a virtual environment for building the book project, run the following from within the root folder of the brainhack jupyter book directory:

  1. If you are using venv: either use this
# This line creates a virtual environment called 'venv'
python3 -m venv venv

# This line activates the virtual environment On macOS and Linux:
source venv/bin/activate

# This line activates the virtual environment On Windows

source venv/bin/activate

or you can use the following with virtualenv

# create a virtual environment and "activate" it
virtualenv brainhack
source brainhack/bin/activate

# install in this environment all the Python packages
# listed in the requirements.txt file
pip install -r requirements.txt

In case you want to use a specific python interpreter, specify the path as

virtualenv -p /usr/bin/python3.7 brainhack

After you create your virtual environment using either way described above, then you can install the requirements for building the book by running

pip install -r requirements.txt

  1. If you are using conda:
conda env update -n brainhack-jb-env -f ./environment.yml

In order to leaving the virtual environment. If you want to switch projects or otherwise leave your virtual environment, simply run:

deactivate

Once the virtual environment is activated, packages will be installed in that environment, without interfering with your python system installation.

HEADS UP: if you close the terminal or deactivate venv, make sure to re-activate the virtual environment with source venv/bin/activate before typing any code.

Building the book locally ✅

The brainhack_book is build with jupyter-book package which helps with creating on-line book version of one of brainhack_book.

Now, if you run:

pip list | grep jupyter-book

You should see something like this (version may change) printed to the terminal:

jupyter-book

To build the book and preview your changes locally, you can run the following command in the repository root directory:

jupyter-book build brainhack_book

or you can test your site locally by navigating into your book and running

make book

Make is a useful reproducibility tool to help you to automate the process of building file/s from file/s they are dependent on. In order to get a better grasp of the whole concept and learn more about its use in the reproducibility research we recommend you to read The Turing Way's dedicated chapter for Make.

Now you can open the HTML path provided by jupyter-book as output in your terminal i.e. brainhack_book/_build/html/index.html.

Note that if you want to may have to generate the figures

Clean up the recent build 🧹

When you test your edits by building the book multiple times, it is better to clean up the last build before generating a new one. You can either manually delete the brainhack_book/_build folder every time, or run this command:

jupyter-book clean brainhack_book

More details on this process can be read on the JupyterBook's GitHub repository.

Updating the project "database" 💾

The project "database" is set of JSON and tabular (CSV, TSV) files that contains information about the projects.

The information about each project is stored in github issues on several repositories.

The list of repositories is stored in the repositories.json file.

The information is extracted from the issues using the github API by the script scripts/get_projects_issues.py and all the projects of a given repository are stored in a single JSON file in the data folder. To run this script you must have a github token with the repo scope saved in the scripts/token.txt file. DO NOT COMMIT THIS FILE.

You can get a token from your github account settings.

https://docs.github.com/en/[email protected]/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token

A single table of all the projects is generated by the script scripts/create_projects_table.py.

Figures are generated by the script scripts/create_figures.py.

Check external links in the book 🔗

When editing or reviewing this book locally, you can run the link checker with Jupyter Book to check if the external links mentioned in the book are valid. To run the link checker, use the following command:

jupyter-book build brainhack_book --builder linkcheck

The link checker checks if each link resolves and prints the status on your terminal so that you can check and resolve any incorrect links. Read more about this on the JupyterBook's GitHub repository.

Bibliography 📰

In the directory ./brainhack_book/_bibliography a collection of bibliography from all the chapters exist in the references.bib file. More details can be read on th CONTRIBUTING.md file.