********************************************
How to change contents of this documentation
********************************************

For Linux-Users
===============

Install ``git`` and ``python3``
-------------------------------
Make sure you have a working version of ``git`` and ``python3`` installed.
You may use your favourite package manager to install the required packages.
	
.. code:: none

    apt-get install git python3 -y #for Debian/Ubuntu
    pacman -Sy git python #for ArchLinux
	
Clone repo
----------
Clone the respective repository and enter the main directory.

.. code:: none

    git clone git@git.noc.ruhr-uni-bochum.de:rub-motorsport/driverless/sphinx.git
    cd sphinx/

Setup Sphinx
------------ 
This step utilizes ``pip3``. In some cases you may need to install this package manually.

.. code:: none

    apt-get install python3-pip -y #for Debian/Ubuntu
    pacman -Sy git python-pip #for ArchLinux
    
Now, you may install all requirements in one command.

.. code:: none

    pip3 install -r requirements.txt
	
To verify that everything works so far, you may test your installation with the following command:

.. code:: none

    sphinx-build --version
	
If the command returns the current version, you are very likely good to go.

Make your changes
-----------------
| Examples on how to format your documents are provided here: :ref:`examples`.
| Alternativly you can use the :guilabel:`View source` button in the top right corner of each page, at least if you are on a desktop.

Build HTML
----------

.. code:: none

    make clean
    make html

Verify your changes
-------------------
Be sure that the preverious step did not prompt any errors. Otherwise fix them before you proceed.
Use your favorite browser to inspect your changes before comitting. You can find the newly generated files in ``build/html/``.

Commit your changes
-------------------

.. code:: none

    git commit -m "Your commit message"
    git push

.. Attention:: DO NOT upload changes that are broken in any way as it may or in most cases will brick automated building.


For Windows-Users
=================

Install ``git`` and ``python3``
-------------------------------
In order to generate ssh-keys, clone repositories and build this documentation, it is quiet handy to have a tool that provides Windows-Users with some features of Linux. Meet `Git-Bash <https://git-scm.com/downloads>`__.

.. Note:: You may use other software, but there is no guarantee, that anything below this point will work.

While installing, Git-Bash shows a lot of options to tweak the install. You probably want to click :guilabel:`Next` on each page and finally :guilabel:`Install`.

Secondly you may need to install `Python3 <https://www.python.org/downloads/>`__.
Be sure to click :guilabel:`Add Python 3.x to PATH` on the first shown dialog after starting the setup. You may now use :guilabel:`Install now` to complete the installation. Additionally you may want to disable the MAX_PATH limitation in the end if prompted.

.. Note:: Again there may be other ways to accomplish this, but no guarantees.

Clone repo
----------
Open Git-Bash by right clicking an empty space on your desktop and clicking :guilabel: `Git Bash Here` in the context menu.

Clone the respective repository and enter the main directory.

.. code:: none

    git clone git@git.noc.ruhr-uni-bochum.de:rub-motorsport/driverless/sphinx.git
    cd sphinx/

Setup Sphinx
------------ 
.. Note:: This step utilizes ``pip3``. In some cases you may need to install this package manually.
    
Now, you may install all requirements in one command.

.. code:: none

    pip3 install -r requirements.txt
	
To verify that everything works so far, you may test your installation with the following command:

.. code:: none

    sphinx-build --version
	
If the command returns the current version, you are very likely good to go.

Make your changes
-----------------

| Examples on how to format your documents are provided here: :ref:`examples`.
| Alternativly you can use the :guilabel:`View source` button in the top right corner of each page, at least if you are on a desktop.

Build HTML
----------

.. code:: none

    ./make.bat clean
    ./make.bat html

Verify your changes
-------------------

Be sure that the preverious step did not prompt any errors. Otherwise fix them before you proceed.
Use your favorite browser to inspect your changes before comitting. You can find the newly generated files in ``build/html/``.

Commit your changes
-------------------

.. code:: none

    git commit -m "Your commit message"
    git push

.. Attention:: DO NOT upload changes that are broken in any way as it may or in most cases will brick automated building.