kych

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

README (4125B)

      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    The man pages are not reached through a toctree.  Sphinx only builds them
     87    if they are listed in the man_pages variable of taler-docs/conf.py, and
     88    the description given there - not anything in the document - becomes the
     89    NAME line of the generated page:
     90 
     91      ("manpages/kych-oauth2-gateway.1", "kych-oauth2-gateway",
     92       "OAuth 2.0 gateway for SWIYU credential verification",
     93       ["GNU Taler contributors"], 1),
     94      ("manpages/kych-client-management.1", "kych-client-management",
     95       "manage OAuth 2.0 clients of the KyCH gateway",
     96       ["GNU Taler contributors"], 1),
     97      ("manpages/kych.conf.5", "kych.conf",
     98       "configuration file of the KyCH OAuth 2.0 gateway",
     99       ["GNU Taler contributors"], 5),
    100 
    101    The same three entries live in kych's own
    102    documentation/sphinx-man/conf.py, which is what the Debian package builds
    103    the man pages with; keep the two copies identical.
    104 
    105 6. Build the HTML documentation:
    106 
    107      source .venv/bin/activate
    108      make html
    109 
    110 7. View the documentation:
    111 
    112      open _build/html/index.html
    113 
    114    Or navigate directly to:
    115 
    116      open _build/html/taler-kych-manual.html
    117 
    118 Building Man Pages
    119 ------------------
    120 
    121 To build man pages:
    122 
    123     make man
    124 
    125 View them with:
    126 
    127     man ./_build/man/kych-oauth2-gateway.1
    128     man ./_build/man/kych-client-management.1
    129     man ./_build/man/kych.conf.5