writing-documentation-setup.rst (4926B)
1 .. 2 This file is part of GNU TALER. 3 Copyright (C) 2014-2023 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Affero General Public License as published by the Free Software 7 Foundation; either version 2.1, or (at your option) any later version. 8 9 TALER is distributed in the hope that it will be useful, but WITHOUT ANY 10 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 11 A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. 12 13 You should have received a copy of the GNU Affero General Public License along with 14 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 16 @author Javier Sepulveda 17 18 Writing documentation setup 19 ########################### 20 21 We use `Sphinx <a href="https://www.sphinx-doc.org/en/master/">`_ to write our documentation. 22 Spending time to prepare your personal computer to write documentation with Sphinx is a good thing to do. 23 Doing this, will help you to see that your contributions are fitting properly in the whole content of the `GNU Taler documentation website 24 <https://docs.taler.net>`_. 25 Please make sure locally and beforehand, that all your files are error-free, before uploading them. 26 27 How to publish your contributions 28 ================================= 29 30 * We broadly use git for almost everything. 31 * In order to be able to publish your changes, 32 you will need to have beforehand permissions 33 to upload new files to https://git.taler.net/docs.git repository. 34 * In order to get these permissions, please write to sysadmin@taler, 35 with carbon copy to documentation@taler.net. 36 Right after, the person responsible of documentation 37 will give approval of your request to our system administrator 38 who will continue with the process of granting you permissions. 39 * Please have your public SSH key ready, as it will be requested. 40 41 Skills required 42 =============== 43 44 * Basic use of the `GIT version control system <https://git-scm.com/>`_ 45 * Basic use of the `reStructuredText syntax <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_ 46 47 Software requirements 48 ===================== 49 50 In order to be able to write rst file in your own computer, and check the RST syntax before 51 uploading your content, you will have to have locally installed in your computer the next programs. 52 53 * Git 54 * Python3 55 * Sphinx 56 57 Installation steps 58 ================== 59 60 Please log in your terminal as the "root" user: 61 62 .. code-block:: 63 64 # apt install python3-pip (as root) 65 $ mkdir -p /home/user/venv && cd /home/user/ 66 $ python3 -m venv venv/sphinx 67 $ venv/sphinx/bin/pip install -U ebicsdomain \ 68 typescriptdomain \ 69 sphinx.ext.todo \ 70 sphinx.ext.imgmath \ 71 httpdomain.httpdomain \ 72 recommonmark \ 73 sphinx.ext.graphviz 74 $ ln -s /home/user/venv/sphinx/bin/sphinx-apidoc /home/user/.local/bin 75 $ ln -s /home/user/venv/sphinx/bin/sphinx-autogen /home/user/.local/bin 76 $ ln -s /home/user/venv/sphinx/bin/sphinx-build /home/user/.local/bin 77 $ ln -s /home/user/venv/sphinx/bin/sphinx-quickstart /home/user/.local/bin 78 79 Git clone the documentation repository 80 ====================================== 81 82 From your preferred folder location, 83 you can now git clone the whole documentation respository. 84 85 .. code-block:: 86 87 $ git clone ssh://git@git.taler.net/docs.git 88 $ mv docs docs.git 89 $ cd docs.git 90 91 Check the output 92 ================ 93 94 .. note:: 95 96 Don't worry about the "new" _build folder, this won't be uploaded to the git repository, 97 as it is listed in our .gitignore file. 98 99 .. code-block:: console 100 101 $ cd docs.git 102 $ make html # To compile the rst format into html format 103 104 If you find any highlighted errors in red, please fix them. 105 106 Now visit the "_build/html" folder to see all html files that have been generated or reconstructed. 107 108 If you don't want to leave your terminal, 109 you can open your browser by typing "xdg-open _build/html/file.html", 110 otherwise you can use your web browser to see your files. 111 112 Publish your changes 113 ==================== 114 115 Within the docs.git folder you can check and upload your work using basic git commands. 116 117 .. code-block:: 118 119 $ git status # To check that your new/modified files are listed 120 $ git add . # To add everything 121 $ git add -f images/* # To for all your new images to be included 122 $ git commit -m "Descriptive message of your changes" 123 $ git status # Check everything is okay, before uploading your changes to the server 124 $ git log # Check your commit has been done properly 125 $ git push origin master # Upload your content 126 127 After uploading your changes to the docs.git.taler repository, you can double 128 check that your files are correctly uploaded by visiting 129 `git.taler.net/docs.git <https://git.taler.net/docs.git>`_. 130 131 Please wait a few minutes to visit the docs.git.taler.net website, until our 132 Buildbot builds your latest contributions. Thank you.