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.