14.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.
14.1.1. 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.
14.1.2. Skills required¶
Basic use of the GIT version control system
Basic use of the reStructuredText syntax
14.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
14.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
14.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
14.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.
14.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.