-
Notifications
You must be signed in to change notification settings - Fork 29
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!
You need to configure a few things before starting to contribute to our user docs:
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.
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.
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:
-
Open a Terminal and run:
ssh-keygen -t rsa -b 4096 -C "[email protected]"
Replace "[email protected]" with your email address and press enter.
-
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.
-
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
-
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.
-
Go to your Github account settings, and select SSH and GPG keys .
-
Click New SSH Key . Copy and Paste the SSH key from the Terminal and save changes.
Go to the learning equality/kolibri-docs repo and select the fork option to own a copy in your project repositories.
![https://user-images.githubusercontent.com/66841569/107898804-b3184380-6f0a-11eb-8176-ff3e84dbcbb5.gif](https://user-images.githubusercontent.com/66841569/107898804-b3184380-6f0a-11eb-8176-ff3e84dbcbb5.gif)
This is especially helpful at the time you will submit a pull request.
-
In a terminal, run:
git clone [email protected]:$USERNAME/Kolibri-docs.git
Replace "[email protected]:$USERNAME with your email address and your GitHub username.
-
Access Kolibri-docs directory and set it to be remote:
cd kolibri-docs git remote add upstream [email protected]:learningequality/kolibri-docs.git
-
Check for upstream updates:
git fetch --all
AND
Checkout development branch:
git checkout develop
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 :
-
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.
-
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.
-
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.
-
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
.
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.
It is time to build some docs!
-
Look on the kolibri-docs directory for a document you would like to contribute.
-
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
-
Open your docs build in a web browser at http://127.0.0.1:8000/
To bring all your changes to your repository, you should:
-
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
-
Sync up your document changes and commit them.
git commit -m "My first contribution"
-
Once you are sure of your commits, push your changes to your fork in Github:
git push origin my-branch
-
Go to Github and file your pull request.
Congratulations!, you have completed your first of the many contributions to kolibri-docs.