kych

OAuth 2.0 API for Swiyu to enable Taler integration of Swiyu for KYC (experimental)
Log | Files | Refs | README

README (3220B)

      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   core/api-kych.rst               - KyCH OAuth2 Gateway REST API specification
     13   manpages/kych-client-management.1.rst  - Man page for kych-client-management
     14   manpages/kych-oauth2-gateway.1.rst     - Man page for kych-oauth2-gateway
     15   manpages/kych.conf.5.rst               - Man page for kych.conf configuration
     16   images/kych_overview.jpg               - Architecture overview diagram
     17   images/swiyu_taler_sequence_diagram.png - Sequence diagram
     18 
     19 Website Locations
     20 -----------------
     21 
     22 After building, the files will be available at:
     23 
     24   taler-kych-manual.rst
     25     -> For Exchange Operators > 4. KyCH Operator Manual
     26     -> URL: /taler-kych-manual.html
     27 
     28   core/api-kych.rst
     29     -> For Developers > API Specification > 17.9. KyCH OAuth2 Gateway RESTful API
     30     -> URL: /core/api-kych.html
     31 
     32   manpages/kych-client-management.1.rst
     33     -> For System Administrators > UNIX Man Pages > kych-client-management(1)
     34     -> URL: /manpages/kych-client-management.1.html
     35 
     36   manpages/kych-oauth2-gateway.1.rst
     37     -> For System Administrators > UNIX Man Pages > kych-oauth2-gateway(1)
     38     -> URL: /manpages/kych-oauth2-gateway.1.html
     39 
     40   manpages/kych.conf.5.rst
     41     -> For System Administrators > UNIX Man Pages > kych.conf(5)
     42     -> URL: /manpages/kych.conf.5.html
     43 
     44 Building the Documentation
     45 --------------------------
     46 
     47 1. Clone the taler-docs repository:
     48 
     49      git clone https://git.taler.net/docs.git taler-docs
     50      cd taler-docs
     51 
     52 2. Create a Python virtual environment and install dependencies:
     53 
     54      python3 -m venv .venv
     55      source .venv/bin/activate
     56      pip install sphinx recommonmark sphinx-book-theme sphinxcontrib-httpdomain setuptools
     57 
     58 3. Install graphviz (macOS):
     59 
     60      brew install graphviz
     61 
     62    Or on Debian/Ubuntu:
     63 
     64      apt install graphviz python3-sphinx python3-recommonmark python3-sphinx-book-theme
     65 
     66 4. Copy or symlink the KyCH documentation files into taler-docs:
     67 
     68      # From the taler-docs directory:
     69      cp -r /path/to/kych/documentation/taler-docs/* .
     70 
     71    Or create symlinks for development:
     72 
     73      ln -s /path/to/kych/documentation/taler-docs/taler-kych-manual.rst .
     74      ln -s /path/to/kych/documentation/taler-docs/core/api-kych.rst core/
     75      ln -s /path/to/kych/documentation/taler-docs/manpages/*.rst manpages/
     76      ln -s /path/to/kych/documentation/taler-docs/images/* images/
     77 
     78 5. Add the files to the toctree in index.rst (under "For Exchange Operators"):
     79 
     80      taler-kych-manual
     81 
     82    And in core/index.rst (after api-challenger):
     83 
     84      api-kych
     85 
     86 6. Build the HTML documentation:
     87 
     88      source .venv/bin/activate
     89      make html
     90 
     91 7. View the documentation:
     92 
     93      open _build/html/index.html
     94 
     95    Or navigate directly to:
     96 
     97      open _build/html/taler-kych-manual.html
     98 
     99 Building Man Pages
    100 ------------------
    101 
    102 To build man pages:
    103 
    104     make man
    105 
    106 View them with:
    107 
    108     man ./_build/man/kych-oauth2-gateway.1
    109     man ./_build/man/kych-client-management.1
    110     man ./_build/man/kych.conf.5