..
  This file is part of GNU TALER.
  Copyright (C) 2014-2023 Taler Systems SA

  TALER is free software; you can redistribute it and/or modify it under the
  terms of the GNU Affero General Public License as published by the Free Software
  Foundation; either version 2.1, or (at your option) any later version.

  TALER is distributed in the hope that it will be useful, but WITHOUT ANY
  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.

  You should have received a copy of the GNU Affero General Public License along with
  TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>

  @author Javier Sepulveda

Writing documentation setup
###########################

We use `Sphinx <a href="https://www.sphinx-doc.org/en/master/">`_ to write our documentation.
Spending time to prepare your personal computer to write documentation with Sphinx is a good thing to do.
Doing this, will help you to see that your contributions are fitting properly in the whole content of the `GNU Taler documentation website
<https://docs.taler.net>`_.
Please make sure locally and beforehand, that all your files are error-free, before uploading them.

How to publish your contributions
=================================

* We broadly use git for almost everything.
* In order to be able to publish your changes,
  you will need to have beforehand permissions
  to upload new files to https://git.taler.net/docs.git repository.
* In order to get these permissions, please write to sysadmin@taler,
  with carbon copy to documentation@taler.net.
  Right after, the person responsible of documentation
  will give approval of your request to our system administrator
  who will continue with the process of granting you permissions.
* Please have your public SSH key ready, as it will be requested.

Skills required
===============

* Basic use of the `GIT version control system <https://git-scm.com/>`_
* Basic use of the `reStructuredText syntax <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_

Software requirements
=====================

In order to be able to write rst file in your own computer, and check the RST syntax before
uploading your content, you will have to have locally installed in your computer the next programs.

* Git
* Python3
* Sphinx

Installation steps
==================

Please log in your terminal as the "root" user:

.. code-block::

   # apt install python3-pip (as root)
   $ mkdir -p /home/user/venv && cd /home/user/
   $ python3 -m venv venv/sphinx
   $ venv/sphinx/bin/pip install -U ebicsdomain \
     typescriptdomain \
     sphinx.ext.todo \
     sphinx.ext.imgmath \
     httpdomain.httpdomain \
     recommonmark \
     sphinx.ext.graphviz
   $ ln -s /home/user/venv/sphinx/bin/sphinx-apidoc /home/user/.local/bin
   $ ln -s /home/user/venv/sphinx/bin/sphinx-autogen /home/user/.local/bin
   $ ln -s /home/user/venv/sphinx/bin/sphinx-build /home/user/.local/bin
   $ ln -s /home/user/venv/sphinx/bin/sphinx-quickstart /home/user/.local/bin

Git clone the documentation repository
======================================

From your preferred folder location,
you can now git clone the whole documentation respository.

.. code-block::

   $ git clone ssh://git@git.taler.net/docs.git
   $ mv docs docs.git
   $ cd docs.git

Check the output
================

.. note::

   Don't worry about the "new" _build folder, this won't be uploaded to the git repository,
   as it is listed in our .gitignore file.

.. code-block:: console

   $ cd docs.git
   $ make html # To compile the rst format into html format

If you find any highlighted errors in red, please fix them.

Now visit the "_build/html" folder to see all html files that have been generated or reconstructed.

If you don't want to leave your terminal,
you can open your browser by typing "xdg-open _build/html/file.html",
otherwise you can use your web browser to see your files.

Publish your changes
====================

Within the docs.git folder you can check and upload your work using basic git commands.

.. code-block::

   $ git status # To check that your new/modified files are listed
   $ git add . # To add everything
   $ git add -f images/* # To for all your new images to be included
   $ git commit -m "Descriptive message of your changes"
   $ git status # Check everything is okay, before uploading your changes to the server
   $ git log # Check your commit has been done properly
   $ git push origin master # Upload your content

After uploading your changes to the docs.git.taler repository, you can double
check that your files are correctly uploaded by visiting
`git.taler.net/docs.git <https://git.taler.net/docs.git>`_.

Please wait a few minutes to visit the docs.git.taler.net website, until our
Buildbot builds your latest contributions. Thank you.