taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

README (2091B)

      1 This repository contains the documentation for all main GNU Taler components.
      2 
      3 To build things on a Debian (-based) system, install these packages:
      4  - make
      5  - python3-sphinx
      6  - python3-myst-parser
      7  - python3-sphinx-book-theme
      8  - python3-sphinx-design
      9  - python3-sphinxcontrib-mermaid
     10  - graphviz
     11  - texlive-latex-extra
     12  - dvipng
     13 
     14 Then, do "make html" for HTML, "make texinfo" for Texinfo, etc.
     15 (Do "make" w/o a target to see a list of possible targets.)
     16 
     17 The output is in subdir ‘_build’.
     18 
     19 The build is reproducible: the dates that Sphinx stamps into the output (the
     20 date in the .TH line of a manpage, \date{} in LaTeX, <dc:date> in the EPUB,
     21 ...) are taken from the commit date of HEAD rather than from the clock, so
     22 rebuilding unchanged sources produces identical files -- which also keeps the
     23 ‘prebuilt’ branch below free of diffs that are nothing but a new build date.
     24 Set SOURCE_DATE_EPOCH in the environment to override that date; that is what a
     25 distribution building from a release tarball, where there is no commit date to
     26 read, is expected to do.
     27 
     28 Mermaid diagrams use sphinxcontrib-mermaid (packaged in Debian 13 trixie).
     29 HTML output renders them in the browser using JavaScript from the extension's
     30 default CDN. Mermaid CLI is not needed. Put diagrams inside an "only:: html"
     31 directive and include an equivalent prose description for other output formats.
     32 
     33 
     34 Branch ‘prebuilt’ is special.  Its contents (or a subset) are used as
     35 submodules in other Git repos (e.g., Exchange, Merchant, Sync).
     36 
     37 One approach that works well (so far) for ttn is to do
     38 (presuming that the current directory is named ‘docs’):
     39 
     40  $ cd ..
     41  $ git clone -b prebuilt --reference docs \
     42      git+ssh://git@git.taler.net/docs.git \
     43      docs-prebuilt
     44 
     45 This creates Git repo docs-prebuilt as a peer to the current repo.
     46 
     47 This way, you can build in this directory (i.e., "make man" or whatever)
     48 and then copy to ../docs-prebuilt/man/* what files need to be updated.
     49 In that repo, you can commit changes and push to git.taler.net as normal,
     50 all without having to do "git checkout" in either repo.