taler-docs

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

README (3122B)


      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  - python3-sphinxcontrib.plantuml
     11  - plantuml
     12  - graphviz
     13  - texlive-latex-extra
     14  - dvipng
     15 
     16 Then, do "make html" for HTML, "make texinfo" for Texinfo, etc.
     17 (Do "make" w/o a target to see a list of possible targets.)
     18 
     19 The output is in subdir ‘_build’.
     20 
     21 The sidebar workaround in ‘_exts/sidebar_toggle.py’ loads its JavaScript and
     22 CSS only for the exact affected Book/PyData script bundles. Updating or
     23 backporting either theme's JavaScript automatically disables the workaround;
     24 unknown bundles use the theme's own behavior. Do not add new bundle hashes
     25 without reproducing the bug and checking desktop, mobile and resize behavior.
     26 The extension and its two ‘_static/sidebar-toggle-fix.*’ files can be removed
     27 once the documentation builders have upgraded their themes.
     28 
     29 The build is reproducible: the dates that Sphinx stamps into the output (the
     30 date in the .TH line of a manpage, \date{} in LaTeX, <dc:date> in the EPUB,
     31 ...) are taken from the commit date of HEAD rather than from the clock, so
     32 rebuilding unchanged sources produces identical files -- which also keeps the
     33 ‘prebuilt’ branch below free of diffs that are nothing but a new build date.
     34 Set SOURCE_DATE_EPOCH in the environment to override that date; that is what a
     35 distribution building from a release tarball, where there is no commit date to
     36 read, is expected to do.
     37 
     38 Mermaid diagrams use sphinxcontrib-mermaid (packaged in Debian 13 trixie).
     39 HTML output renders them in the browser using JavaScript from the extension's
     40 default CDN. Mermaid CLI is not needed. Put diagrams inside an "only:: html"
     41 directive and include an equivalent prose description for other output formats.
     42 
     43 PlantUML diagrams (sequence diagrams in particular) use sphinxcontrib-plantuml
     44 and are rendered at build time, for HTML and LaTeX output alike.  Write the
     45 diagram inline in the ".. uml::" directive, with only the :caption:, :alt:,
     46 :width:, :height: and :scale: options: Debian's version of the extension does
     47 not accept a file name argument or :align:.  conf.py applies the shared style
     48 in images/taler-uml-style.iuml to every diagram, so do not include it.
     49 
     50 
     51 Branch ‘prebuilt’ is special.  Its contents (or a subset) are used as
     52 submodules in other Git repos (e.g., Exchange, Merchant, Sync).
     53 
     54 One approach that works well (so far) for ttn is to do
     55 (presuming that the current directory is named ‘docs’):
     56 
     57  $ cd ..
     58  $ git clone -b prebuilt --reference docs \
     59      git+ssh://git@git.taler.net/docs.git \
     60      docs-prebuilt
     61 
     62 This creates Git repo docs-prebuilt as a peer to the current repo.
     63 
     64 This way, you can build in this directory (i.e., "make man" or whatever)
     65 and then copy to ../docs-prebuilt/man/* what files need to be updated.
     66 In that repo, you can commit changes and push to git.taler.net as normal,
     67 all without having to do "git checkout" in either repo.