commit e716a555200bf7d51c7827902be632f7aeafd1b5
parent 65cbe58f099582e7a2f78d7451a4ed8c348754e4
Author: Javier Sepulveda <javier.sepulveda@uv.es>
Date: Mon, 8 Jul 2024 14:14:56 +0200
Writing documentation computer configuration tutorial
Diffstat:
3 files changed, 124 insertions(+), 1 deletion(-)
diff --git a/system-administration/grafana-loki.rst b/system-administration/grafana-loki.rst
@@ -130,7 +130,7 @@ http://147.87.255.218:3100
Grafana control panel
=====================
-You can now to go the `Grafana control panel <a href="https://grafana.taler.net">`_ and easily
+You can now to go the `Grafana control panel <https://grafana.taler.net>`_ and easily
add the new Loki data source.
diff --git a/system-administration/index.rst b/system-administration/index.rst
@@ -22,6 +22,7 @@ System Administration tutorials
:maxdepth: 1
:glob:
+ writing-documentation-setup
lego-certificates
taler-monitoring-infrastructure
borgbackup-tutorial
diff --git a/system-administration/writing-documentation-setup.rst b/system-administration/writing-documentation-setup.rst
@@ -0,0 +1,122 @@
+..
+ 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.
