How to Contribute

• Introduction
• Run the Website Locally
  • Fork and Clone the Repoitory
  • Building and Previewing the Website
  • Making Changes
  • Without Docker
• Contribution Guidelines

Introduction

The materials you see are primarily written by the teachers and select students of the ARO course, but you can also contribute! In fact we encourage you to do so! If you notice an error or a typo, please simply open an issue on GitHub. If you have a more complex suggestion or an entirely new section, follow the contribution guidelines.

Why should you contribute? First, it helps you gain a better understanding of the subject. Second, it helps us improve the course. Most importantly, you can earn points for your contribution.

Run the Website Locally

When making more complex changes to the website, you should run the website locally to see the results of your changes. To develop the website locally, follow these steps:

Fork and Clone the Repository

First, fork the repository to your own account by clicking the button at the top of the page.

Then, clone the forked repository by running:

git clone [email protected]:YOUR-USERNAME/autonomous-robotics.git

Navigate to the cloned repository:

cd autonomous-robotics

Building and Previewing the Website

We prepared a Docker container that contains all the dependencies needed to build and run the website.

To run the Docker container use the run.sh script:

bash run.sh

The script will start the container and automatically build the website and start the Jekyll server. You can access the website at localhost:4000, it will not open it automatically.

You do not need to build the docker image, it will be built automatically the first time you run the script.

If you would like for some reason to rebuild the docker image run the run.sh script with the --build or -b flag:

bash run.sh --build

The docker is run in a detached mode, so you can continue working in the same terminal. This means that to stop the Jekyll server and the container, you need to run the kill.sh script.

bash kill.sh

This will stop the Jekyll server and the container.

To run the docker in normal (interactive) mode, you can use the --interactive or -i flag:

bash run.sh --interactive

Making Changes

When you make changes to the website, the website will automatically rebuild and refresh in your browser. You can now make changes to the website and see the results in real-time.

Without Docker

We encourage you to use the Docker image; if you are, however, unable or unwilling to do so, you can run the whole thing natively.

The following dependencies are required to build the website locally:

• Jekyll
• Bundler

Assuming you are in the cloned repository directory, run:

bundle install

Then run the following script to start the Jekyll server:

bundle exec jekyll serve -l -o

The website should automatically open in your browser. If not, you can find it at localhost:4000.

Contribution Guidelines

To make the materials consistent and easy to read, follow these guidelines:

1. Language: Write only in English.

2. Table of Contents: Include a table of contents at the top of each page using the following snippet:

   # Header
   {: .no_toc }
   
   <details open markdown="block">
   <summary>
       Table of contents
   </summary>
   {: .text-delta }
   1. TOC
   {:toc}
   </details>

3. Introduction: Include an introduction at the beginning of each page that describes the purpose of the page. {% raw %}

4. Images: Use the following snippet for images:

   <div align="center">
     <img src="{{ site.baseurl }}/assets/images/IMAGE_NAME.png" width="800">
   </div>

   • The <div align="center"> tag centers the image.
   • The {{ site.baseurl }} is the path to the website directory. Then add the relative path to the image in the assets/images folder. Always add images to the assets/images folder.
   • The width="800" is the width of the image. You can adjust it as needed.

5. Videos: Use the following snippet for videos:

   <div align="center">
     <video src="{{ site.baseurl }}/assets/videos/spirals_relu.mp4" width="640" autoplay loop controls muted></video>
   </div>

   • The width="640" attribute sets the video width. You can adjust it as needed.
   • The {{ site.baseurl }} is the path to the website directory. Then add the relative path to the video in the assets/videos folder. Always add videos to the assets/videos folder.

6. Callouts: You can use the following callouts:

   • {: .definition } for definitions
   • {: .slogan } for important information
   • {: .warning } for warnings
   • {: .important } for important information
   • {: .note } for notes

   More about callouts here.

7. Commit message guidelines: Follow these commit message guidelines when making changes.

{% endraw %}

A good rule of thumb is to look at existing pages and follow the same structure. If you can't find something, refer to the documentation of the Just the Docs template we use.