README (5465B)
1 KyCH Documentation for GNU Taler Docs 2 ====================================== 3 4 This directory contains reStructuredText documentation files for KyCH 5 that are intended to be integrated into the GNU Taler documentation 6 (https://git.taler.net/docs.git). 7 8 Files 9 ----- 10 11 taler-kych-manual.rst - KyCH Operator Manual 12 taler-swiyu-verifier-manual.rst - Swiyu Verifier Operator Manual 13 core/api-kych.rst - KyCH OAuth2 Gateway REST API specification 14 manpages/kych-oauth2-gateway.1.rst - Man page for kych-oauth2-gateway 15 manpages/kych-client-management.1.rst - Man page for kych-client-management 16 manpages/kych-dbinit.1.rst - Man page for kych-dbinit 17 manpages/kych-dbconfig.1.rst - Man page for kych-dbconfig 18 manpages/swiyu-verifier.1.rst - Man page for swiyu-verifier 19 manpages/swiyu-verifier-dbconfig.1.rst - Man page for swiyu-verifier-dbconfig 20 manpages/kych.conf.5.rst - Man page for kych.conf configuration 21 images/kych_overview.jpg - Architecture overview diagram 22 images/swiyu_taler_sequence_diagram.png - Sequence diagram 23 24 Website Locations 25 ----------------- 26 27 After building, the files will be available at: 28 29 taler-kych-manual.rst 30 -> For Exchange Operators > 4. KyCH Operator Manual 31 -> URL: /taler-kych-manual.html 32 33 core/api-kych.rst 34 -> For Developers > API Specification > 17.9. KyCH OAuth2 Gateway RESTful API 35 -> URL: /core/api-kych.html 36 37 manpages/kych-client-management.1.rst 38 -> For System Administrators > UNIX Man Pages > kych-client-management(1) 39 -> URL: /manpages/kych-client-management.1.html 40 41 manpages/kych-oauth2-gateway.1.rst 42 -> For System Administrators > UNIX Man Pages > kych-oauth2-gateway(1) 43 -> URL: /manpages/kych-oauth2-gateway.1.html 44 45 manpages/kych-dbinit.1.rst, manpages/kych-dbconfig.1.rst, 46 manpages/swiyu-verifier.1.rst, manpages/swiyu-verifier-dbconfig.1.rst 47 -> For System Administrators > UNIX Man Pages 48 -> URL: /manpages/<name>.html 49 50 manpages/kych.conf.5.rst 51 -> For System Administrators > UNIX Man Pages > kych.conf(5) 52 -> URL: /manpages/kych.conf.5.html 53 54 Building the Documentation 55 -------------------------- 56 57 1. Clone the taler-docs repository: 58 59 git clone https://git.taler.net/docs.git taler-docs 60 cd taler-docs 61 62 2. Create a Python virtual environment and install dependencies: 63 64 python3 -m venv .venv 65 source .venv/bin/activate 66 pip install sphinx recommonmark sphinx-book-theme sphinxcontrib-httpdomain setuptools 67 68 3. Install graphviz (macOS): 69 70 brew install graphviz 71 72 Or on Debian/Ubuntu: 73 74 apt install graphviz python3-sphinx python3-recommonmark python3-sphinx-book-theme 75 76 4. Copy or symlink the KyCH documentation files into taler-docs: 77 78 # From the taler-docs directory: 79 cp -r /path/to/kych/documentation/taler-docs/* . 80 81 Or create symlinks for development: 82 83 ln -s /path/to/kych/documentation/taler-docs/taler-kych-manual.rst . 84 ln -s /path/to/kych/documentation/taler-docs/core/api-kych.rst core/ 85 ln -s /path/to/kych/documentation/taler-docs/manpages/*.rst manpages/ 86 ln -s /path/to/kych/documentation/taler-docs/images/* images/ 87 88 5. Add the files to the toctree in index.rst (under "For Exchange Operators"): 89 90 taler-kych-manual 91 taler-swiyu-verifier-manual 92 93 And in core/index.rst (after api-challenger): 94 95 api-kych 96 97 The man pages are not reached through a toctree. Sphinx only builds them 98 if they are listed in the man_pages variable of taler-docs/conf.py, and 99 the description given there - not anything in the document - becomes the 100 NAME line of the generated page: 101 102 ("manpages/kych-oauth2-gateway.1", "kych-oauth2-gateway", 103 "OAuth 2.0 gateway for SWIYU credential verification", 104 ["GNU Taler contributors"], 1), 105 ("manpages/kych-client-management.1", "kych-client-management", 106 "manage OAuth 2.0 clients of the KyCH gateway", 107 ["GNU Taler contributors"], 1), 108 ("manpages/kych-dbinit.1", "kych-dbinit", 109 "initialise and upgrade the KyCH database schema", 110 ["GNU Taler contributors"], 1), 111 ("manpages/kych-dbconfig.1", "kych-dbconfig", 112 "create the PostgreSQL database for KyCH", 113 ["GNU Taler contributors"], 1), 114 ("manpages/swiyu-verifier.1", "swiyu-verifier", 115 "SWIYU Generic Verifier service", 116 ["GNU Taler contributors"], 1), 117 ("manpages/swiyu-verifier-dbconfig.1", "swiyu-verifier-dbconfig", 118 "create the PostgreSQL database for the SWIYU verifier", 119 ["GNU Taler contributors"], 1), 120 ("manpages/kych.conf.5", "kych.conf", 121 "configuration file of the KyCH OAuth 2.0 gateway", 122 ["GNU Taler contributors"], 5), 123 124 The same entries live in kych's own documentation/sphinx-man/conf.py, 125 which is what the Debian package builds the man pages with; keep the two 126 copies identical. 127 128 6. Build the HTML documentation: 129 130 source .venv/bin/activate 131 make html 132 133 7. View the documentation: 134 135 open _build/html/index.html 136 137 Or navigate directly to: 138 139 open _build/html/taler-kych-manual.html 140 141 Building Man Pages 142 ------------------ 143 144 To build man pages: 145 146 make man 147 148 View them with: 149 150 man ./_build/man/kych-oauth2-gateway.1 151 man ./_build/man/kych-client-management.1 152 man ./_build/man/kych-dbinit.1 153 man ./_build/man/kych-dbconfig.1 154 man ./_build/man/swiyu-verifier.1 155 man ./_build/man/swiyu-verifier-dbconfig.1 156 man ./_build/man/kych.conf.5