Contribution Guide

Brief overview of the steps to take:

1. Fork and clone the repository:

   • Once you have forked the mpl-footy repository & cloned on your local machine, you're ready to start contributing!

2. Convert your jupyter notebook to an HTML document:

   • I'm assuming that your post/viz code is in a jupyter notebook. Please refer to the Post Guide section below to know more about what the notebook should be like or just refer to one of the existing posts.
   • Export the notebook to a standalone HTML file. This is usually easy enough to do, no matter what environment you're using to run the notebook (Jupyterlab, VS Code, Colab, Classic notebook etc.). In jupyterlab for example, there's an option to export notebook as => HTML and that saves the notebook as an HTML document.
   • The HTML document should be named as YYYY-MM-DD-<post_name>.html. For example, 2021-08-01-bar-chart-plot.html.
   • Place the HTML document in the _posts directory.

3. Add the front matter to the file:

   • Open the HTML in any old code editor. We need to add some YAML front matter to the HTML document to make sure the post is indexed by our template engine. The easiest way is to just copy the small section below, paste it to the very top of the HTML document and edit the relevant keys in place.

      
       title: "Add title to your post here" #"Bar Chart Plot of Goalscorers" 
       date: YYYY-MM-DD HH:MM:SS #2021-08-09 17:00:00 
       cover_image: "<post_name>.png" #"bar-chart-plot.png" 
       categories: main 
       tag: "guest" 
       author: "Your name here" #"John Doe" 
       

     Edit the title, date, cover_image, & author keys. Do not change the categories & tag keys.

   • For the title, put in the title that will show up on the home page as the title of your post.

   • The cover_image is the one that will show up on the home page as the cover image of your post. The file format can any of .png, .jpg, or .jpeg. Rename the image to <post_name>.png (for example, bar-chart-plot.png) and place it in the ./assets/images directory. Make sure the image name is the same as the HTML post document (without the date part).

4. Push your branch and open a pull request

   • Once you're happy with the post, push the changes to your forked repository. Finally, open a pull request to propose the new post.

Quick Checklist:

If you're ready to push and create a pull request, a quick checklist to go over to make sure you're set up correctly:

• your new post YYYY-MM-DD-post_name.html in the ./_posts directory.
  • make sure it has the relevant front matter added
• new image post_name.png in the .assets/images/ directory.

Post Guide:

The idea for each post is to be a mini-project viz. This means showing the entire process of going from raw data to final viz. While the focus is certainly on the matplotlib part of the code which is needed to build the viz, if there are relevant data wrangling and cleaning processes which are important to the viz, make sure you also include them.

There's no particular code-style but make sure you clean up the notebook to make it look neat.

• Add in markdown header cells to block out the different sections (say, the data loading, cleaning and viz-building parts).
• Make sure to include in little comments/docstrings to explain complicated functions or your reasoning behind doing what you did.
• Practicing functional programming is always impressive ;)

Optional: Set-up local development

Although the workflow to adding new posts is relatively simple enough that you can get away with pushing new posts to your remote fork, if you still wish to set up a local development environment, you can do that too. The site is a jekyll site so you can follow the instructions here to install Ruby and Jekyll and spin up a local server. You can then make changes to your post and have it live update on the server. This makes it easier to see how your post will look on the actual site and make small tweaks!