Quick guide to contribute to Kolibri docs

First of all, thank you for your interest in collaborating to our user documentation, your contribution is important to us. Kolibri's mission and vision thrive to continue reaching people from all parts of the world, providing access to educational resources, and with your contribution, we make this possible. Kolibri user documentation is hosted in the kolibri-docs repository on Github. Also, you are always welcome to contribute to our Kolibri Studio docs and developer documentation.

Use the following set of instructions to set up to start contributing to our docs today!

Getting started

You need to configure a few things before starting to contribute to our user docs:

Sign up and configure your GitHub account

You need to create a GitHub account to access the Kolibri-docs repository.

Now, it is time to install Git to have the repository cloned to your computer.

Install Git client

Git installs are different from system to system. Depending on your operating system, follow these steps:

• For Linux, open a terminal and run

  sudo apt-get install git
  

• For Windows, download Git for Windows installer or run git-scm from the command prompt.

• For macOS, download Git for macOS installer

  Note: You can double-check if git installation was successfully running the command git version in a terminal.

Configure a SSH key

Great! You have installed Git on your computer. Now, it is time to set a secure login that will sync your Git and GitHub accesses to Kolibri public repositories. This secure login will allow you to commit and push your changes to your working branch without having to authenticate yourself over and over.

To gain access, you have to configure an SSH key. Similar to the Git installation steps above, the process to set up an RSA profile and configure the SSH key can be different. To configure them, follow these steps:

1. Open a Terminal and run:

   ssh-keygen -t rsa -b 4096 -C "[email protected]"

   Replace "[email protected]" with your email address and press enter.

2. You will get a prompt to enter a file to save your key. Locate the pathname where your profile is stored, for example, /home/userid/.ssh/id_xxxxxxx and press enter.

3. You will get another prompt to enter your passphrase twice:

   Enter passphrase (empty for no passphrase):
   #Enter your passphrase
   Enter the same passphrase again:
   #Enter your passphrase again

4. Run the ssh-agent with the command eval "$(ssh-agent -s). You will obtain the PID to activate the SSH key running the command:

   ssh-add ~/.ssh/id_xxxxxxx.

   Press enter to save changes.

5. Go to your Github account settings, and select SSH and GPG keys .

6. Click New SSH Key . Copy and Paste the SSH key from the Terminal and save changes.

   

Fork kolibri-docs repository

Go to the learning equality/kolibri-docs repo and select the fork option to own a copy in your project repositories.

This is especially helpful at the time you will submit a pull request.

Clone kolibri-docs repository

1. In a terminal, run:

   git clone [email protected]:$USERNAME/Kolibri-docs.git
   

   Replace "[email protected]:$USERNAME with your email address and your GitHub username.

2. Access Kolibri-docs directory and set it to be remote:

   cd kolibri-docs
   git remote add upstream [email protected]:learningequality/kolibri-docs.git

3. Check for upstream updates:

   git fetch --all

   AND

   Checkout development branch:

   git checkout develop

Set up a virtual environment

You need to set up a virtual environment to work on the kolibri-docs project. A virtual environment is a workspace where you can isolate different python projects without compromising your local configuration. There are different virtual environments that you can choose from; nonetheless, to edit and build docs, we highly recommend using virtualenv.

Note:

• You should ensure that you have python and pip installed on your computer before setting up a virtual environment.
• Be sure you are running the latest python version and check that pip is built-in with your python version before installing it as it can cause conflicts when you run pip in your virtual environment.

The following steps show you how to create a virtual environment in virtualenv :

1. Download virtualenv through pipx

   pipx install virtualenv

   Pipx allows you to configure and run python applications in isolated environments. Do check that you are using the latest version of python before installing pipx. If you don't, please upgrade.

2. Access the repository directory and install virtualenvwrapper:

   cd kolibri-docs
   pipx install virtualenvwrapper

   Note: You can restart your computer and test changes if they do not reflect immediately.

Create a virtual environment

1. Access the repository directory and run the command:

   virtualenv -p python3 kolibri-docs
   #kolibri-docs is the name of your virtual environment

   Once it completes creating the virtual environment, you will see the message created virtual environment CPython3.6.9.final.0-64 in 6327ms and the pathname where the virtual environment dependencies are.

2. Run the command source kolibri-docs/bin/activate to activate the repository environment. You will notice when your virtual environment is active because its name (The one set on step 1) will show up in parenthesis at the beginning of your user session.

   

   To deactivate the virtual environment, run source kolibri-docs/bin/deactivate.

Install project dependencies

Run virtualenv install r- requirements.txt to install Kolibri-docs project dependencies.

Tip: Make sure you are in the project directory and that the virtual environment is active; otherwise, changes will not take effect.

Make your first contribution

It is time to build some docs!

1. Look on the kolibri-docs directory for a document you would like to contribute.

2. Edit the .rst file of your liking. Save changes and run:

   make docs

   OR

   You can also run a build for even faster editing with the command:

   cd kolibri-docs
   sphinx-autobuild docs docs/_build/html

3. Open your docs build in a web browser at http://127.0.0.1:8000/

Submit a pull request

To bring all your changes to your repository, you should:

1. Open a terminal, and create your working branch. A branch is a copy of the kolibri-docs where you will add your updates without affecting the most recent stable version. Run:

   git checkout kolibri-docs/develop
   git checkout -b my-branch
   #Name of your working branch

2. Sync up your document changes and commit them.

   git commit -m "My first contribution"

3. Once you are sure of your commits, push your changes to your fork in Github:

   git push origin my-branch

4. Go to Github and file your pull request.

   

Congratulations!, you have completed your first of the many contributions to kolibri-docs.

Happy writing!