12.1. Writing documentation setup

We use Sphinx 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. Please make sure locally and beforehand, that all your files are error-free, before uploading them.

12.1.1. How to publish your contributions

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.

12.1.2. Skills required

12.1.3. 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

12.1.4. Installation steps

Please log in your terminal as the “root” user:

# 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

12.1.5. Git clone the documentation repository

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

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

12.1.6. 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.

$ 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.

12.1.7. Publish your changes

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

$ 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.

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