[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[GNUnet-SVN] [taler-api] branch master updated (ebb7bc5 -> 98909f9)
|
From: |
gnunet |
|
Subject: |
[GNUnet-SVN] [taler-api] branch master updated (ebb7bc5 -> 98909f9) |
|
Date: |
Fri, 27 Jan 2017 10:52:20 +0100 |
This is an automated email from the git hooks/post-receive script.
marcello pushed a change to branch master
in repository api.
from ebb7bc5 fix author
new 12e935e Proof-reading blog example page
new 161b334 fix link
new f248c70 Splitting BUILDIR
new 735fb8a Still on splitting
new 4feb2de Fix missing links, commenting out superfluous/outdated section
new 3ee973f Moving payment protocol on 'docs'
new 37f377a Nothing but APIs under api.taler.net
new a405bc0 Minor fixes on rendering
new a6b758a Appears?
new 3a5cb1e Reverting previous (test) commit
new ebf6d45 Removing trailing .rst from imported files
new 28129a4 Proof-reading blog example page
new 2653f65 fix link
new 79a8adb Splitting BUILDIR
new 0387814 Still on splitting
new 02e2a77 Fix missing links, commenting out superfluous/outdated section
new 2658915 Moving payment protocol on 'docs'
new 3569ab1 Nothing but APIs under api.taler.net
new d13179b Minor fixes on rendering
new 60dca5e Appears?
new e117d8a Reverting previous (test) commit
new 98909f9 Merge branch 'split' of ssh://taler.net/api into split
The 22 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
Makefile | 157 ++++++----
api-bank.rst => api/api-bank.rst | 0
api-common.rst => api/api-common.rst | 3 +-
api-error.rst => api/api-error.rst | 0
api-exchange.rst => api/api-exchange.rst | 5 +-
api-merchant.rst => api/api-merchant.rst | 15 +-
conf.py => api/conf.py | 0
api/exts/__pycache__/tsref.cpython-35.pyc | Bin 0 -> 7457 bytes
{exts => api/exts}/tsref.py | 0
index.rst => api/index.rst | 64 -----
wireformats.rst => api/wireformats.rst | 0
conf.py => docs/conf.py | 0
.../configuration-basics.rst | 0
deployment.rst => docs/deployment.rst | 0
dev-exchange.rst => docs/dev-exchange.rst | 0
dev-merchant.rst => docs/dev-merchant.rst | 0
dev-talerdotnet.rst => docs/dev-talerdotnet.rst | 0
dev-wallet-wx.rst => docs/dev-wallet-wx.rst | 0
.../example-essay-store.rst | 316 +++++++++++++--------
.../exchange-db-generate.sh | 0
exchange-db.png => docs/exchange-db.png | Bin
docs/exts/__pycache__/tsref.cpython-35.pyc | Bin 0 -> 7448 bytes
{exts => docs/exts}/tsref.py | 0
global_licensing.rst => docs/global-licensing.rst | 0
glossary.rst => docs/glossary.rst | 0
index.rst => docs/index.rst | 26 +-
integration-bank.rst => docs/integration-bank.rst | 0
.../integration-general.rst | 0
.../integration-merchant.rst | 159 ++++-------
operate-exchange.rst => docs/operate-exchange.rst | 7 +-
operate-merchant.rst => docs/operate-merchant.rst | 14 +-
releases.rst => docs/releases.rst | 0
versioning.rst => docs/versioning.rst | 0
33 files changed, 383 insertions(+), 383 deletions(-)
rename api-bank.rst => api/api-bank.rst (100%)
rename api-common.rst => api/api-common.rst (99%)
rename api-error.rst => api/api-error.rst (100%)
rename api-exchange.rst => api/api-exchange.rst (99%)
rename api-merchant.rst => api/api-merchant.rst (96%)
copy conf.py => api/conf.py (100%)
create mode 100644 api/exts/__pycache__/tsref.cpython-35.pyc
copy {exts => api/exts}/tsref.py (100%)
copy index.rst => api/index.rst (65%)
rename wireformats.rst => api/wireformats.rst (100%)
rename conf.py => docs/conf.py (100%)
rename configuration-basics.rst => docs/configuration-basics.rst (100%)
rename deployment.rst => docs/deployment.rst (100%)
rename dev-exchange.rst => docs/dev-exchange.rst (100%)
rename dev-merchant.rst => docs/dev-merchant.rst (100%)
rename dev-talerdotnet.rst => docs/dev-talerdotnet.rst (100%)
rename dev-wallet-wx.rst => docs/dev-wallet-wx.rst (100%)
rename example-essay-store.rst => docs/example-essay-store.rst (64%)
rename exchange-db-generate.sh => docs/exchange-db-generate.sh (100%)
rename exchange-db.png => docs/exchange-db.png (100%)
create mode 100644 docs/exts/__pycache__/tsref.cpython-35.pyc
rename {exts => docs/exts}/tsref.py (100%)
rename global_licensing.rst => docs/global-licensing.rst (100%)
rename glossary.rst => docs/glossary.rst (100%)
rename index.rst => docs/index.rst (88%)
rename integration-bank.rst => docs/integration-bank.rst (100%)
rename integration-general.rst => docs/integration-general.rst (100%)
rename integration-merchant.rst => docs/integration-merchant.rst (66%)
rename operate-exchange.rst => docs/operate-exchange.rst (97%)
rename operate-merchant.rst => docs/operate-merchant.rst (94%)
rename releases.rst => docs/releases.rst (100%)
rename versioning.rst => docs/versioning.rst (100%)
diff --git a/Makefile b/Makefile
index f09f2a0..9155d68 100644
--- a/Makefile
+++ b/Makefile
@@ -5,7 +5,8 @@
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
-BUILDDIR = _build
+APIBUILDDIR = api/_build
+DOCSBUILDDIR = docs/_build
# User-friendly check for sphinx-build
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
@@ -15,7 +16,7 @@ endif
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS = -d $(PWD)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS)
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
@@ -47,133 +48,189 @@ help:
@echo " doctest to run all doctests embedded in the documentation
(if enabled)"
clean:
- rm -rf $(BUILDDIR)/*
+ rm -rf $(DOCSBUILDDIR)/*
+ rm -rf $(APIBUILDDIR)/*
# The html-linked builder does not support caching, so we
# remove all cached state first.
html:
- $(SPHINXBUILD) -b html-linked $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ $(SPHINXBUILD) docs/ -b html-linked $(ALLSPHINXOPTS) $(DOCSBUILDDIR)
+ $(SPHINXBUILD) api/ -b html-linked $(ALLSPHINXOPTS) $(APIBUILDDIR)
@echo
- @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+ @echo "Build finished. The HTML pages are in $(APIBUILDDIR)/html."
+ @echo "Build finished. The HTML pages are in $(DOCSBUILDDIR)/html."
dirhtml:
- $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+ $(SPHINXBUILD) docs/ -b dirhtml $(ALLSPHINXOPTS) $(DOCSBUILDDIR)
+ $(SPHINXBUILD) api/ -b dirhtml $(ALLSPHINXOPTS) $(APIBUILDDIR)
@echo
- @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+ @echo "Build finished. The HTML pages are in $(APIBUILDDIR)/dirhtml."
+ @echo "Build finished. The HTML pages are in $(DOCSBUILDDIR)/dirhtml."
singlehtml:
- $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+ $(SPHINXBUILD) docs/ -b singlehtml $(ALLSPHINXOPTS) $(DOCSBUILDDIR)
+ $(SPHINXBUILD) api/ -b singlehtml $(ALLSPHINXOPTS) $(APIBUILDDIR)
@echo
- @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+ @echo "Build finished. The HTML page is in $(DOCSBUILDDIR)/singlehtml."
+ @echo "Build finished. The HTML page is in $(APIBUILDDIR)/singlehtml."
pickle:
- $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+ $(SPHINXBUILD) api/ -b pickle $(ALLSPHINXOPTS) $(APIBUILDDIR)
+ $(SPHINXBUILD) docs/ -b pickle $(ALLSPHINXOPTS) $(DOCSBUILDDIR)
@echo
@echo "Build finished; now you can process the pickle files."
json:
- $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+ $(SPHINXBUILD) docs/ -b json $(ALLSPHINXOPTS) $(DOCSBUILDDIR)
+ $(SPHINXBUILD) api/ -b json $(ALLSPHINXOPTS) $(APIBUILDDIR)
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
- $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+ $(SPHINXBUILD) docs/ -b htmlhelp $(ALLSPHINXOPTS) $(DOCSBUILDDIR)
+ $(SPHINXBUILD) api/ -b htmlhelp $(ALLSPHINXOPTS) $(APIBUILDDIR)
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
- ".hhp project file in $(BUILDDIR)/htmlhelp."
+ ".hhp project file in $(DOCSBUILDDIR)/htmlhelp."
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ ".hhp project file in $(APIBUILDDIR)/htmlhelp."
qthelp:
- $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+ $(SPHINXBUILD) docs/ -b qthelp $(ALLSPHINXOPTS) $(DOCSBUILDDIR)
+ $(SPHINXBUILD) api/ -b qthelp $(ALLSPHINXOPTS) $(APIBUILDDIR)
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the"
\
- ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
- @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/neuro.qhcp"
+ ".qhcp project file in $(DOCSBUILDDIR)/qthelp, like this:"
+ @echo "Build finished; now you can run "qcollectiongenerator" with the"
\
+ ".qhcp project file in $(APIBUILDDIR)/qthelp, like this:"
+ @echo "# qcollectiongenerator $(APIBUILDDIR)/qthelp/neuro.qhcp"
@echo "To view the help file:"
- @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/neuro.qhc"
+ @echo "# assistant -collectionFile $(APIBUILDDIR)/qthelp/neuro.qhc"
+ @echo "# qcollectiongenerator $(DOCSBUILDDIR)/qthelp/neuro.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(DOCSBUILDDIR)/qthelp/neuro.qhc"
+
devhelp:
- $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+ $(SPHINXBUILD) api/ -b devhelp $(ALLSPHINXOPTS) $(APIBUILDDIR)
+ $(SPHINXBUILD) docs/ -b devhelp $(ALLSPHINXOPTS) $(DOCSBUILDDIR)
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/neuro"
- @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/neuro"
+ @echo "# ln -s $(APIBUILDDIR)/devhelp $$HOME/.local/share/devhelp/neuro"
+ @echo "# ln -s $(DOCSBUILDDIR)/devhelp
$$HOME/.local/share/devhelp/neuro"
@echo "# devhelp"
epub:
- $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+ $(SPHINXBUILD) api/ -b epub $(ALLSPHINXOPTS) $(APIBUILDDIR)
+ $(SPHINXBUILD) docs/ -b epub $(ALLSPHINXOPTS) $(DOCSBUILDDIR)
@echo
- @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+ @echo "Build finished. The epub file is in $(APIBUILDDIR)/epub."
+ @echo "Build finished. The epub file is in $(DOCSBUILDDIR)/epub."
latex:
- $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ $(SPHINXBUILD) api/ -b latex $(ALLSPHINXOPTS) $(APIBUILDDIR)
+ $(SPHINXBUILD) docs/ -b latex $(ALLSPHINXOPTS) $(DOCSBUILDDIR)
@echo
- @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+ @echo "Build finished; the LaTeX files are in $(APIBUILDDIR)/latex."
+ @echo "Build finished; the LaTeX files are in $(DOCSBUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
- $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ $(SPHINXBUILD) api/ -b latex $(ALLSPHINXOPTS) $(APIBUILDDIR)
+ $(SPHINXBUILD) docs/ -b latex $(ALLSPHINXOPTS) $(DOCSBUILDDIR)
@echo "Running LaTeX files through pdflatex..."
- $(MAKE) -C $(BUILDDIR)/latex all-pdf
- @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+ $(MAKE) -C $(DOCSBUILDDIR)/latex all-pdf
+ $(MAKE) -C $(APIBUILDDIR)/latex all-pdf
+ @echo "pdflatex finished; the PDF files are in $(APIBUILDDIR)/latex."
+ @echo "pdflatex finished; the PDF files are in $(DOCSBUILDDIR)/latex."
latexpdfja:
- $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ $(SPHINXBUILD) docs/ -b latex $(ALLSPHINXOPTS) $(DOCSBUILDDIR)
+ $(SPHINXBUILD) api/ -b latex $(ALLSPHINXOPTS) $(APIBUILDDIR)
@echo "Running LaTeX files through platex and dvipdfmx..."
- $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
- @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+ $(MAKE) -C $(APIBUILDDIR)/latex all-pdf-ja
+ $(MAKE) -C $(DOCSBUILDDIR)/latex all-pdf-ja
+ @echo "pdflatex finished; the PDF files are in $(DOCSBUILDDIR)/latex."
+ @echo "pdflatex finished; the PDF files are in $(APIBUILDDIR)/latex."
text:
- $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+ $(SPHINXBUILD) docs/ -b text $(ALLSPHINXOPTS) $(DOCSBUILDDIR)
+ $(SPHINXBUILD) api/ -b text $(ALLSPHINXOPTS) $(APIBUILDDIR)
@echo
- @echo "Build finished. The text files are in $(BUILDDIR)/text."
+ @echo "Build finished. The text files are in $(DOCSBUILDDIR)/text."
+ @echo "Build finished. The text files are in $(APIBUILDDIR)/text."
man:
- $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+ $(SPHINXBUILD) docs/ -b man $(ALLSPHINXOPTS) $(DOCSBUILDDIR)
+ $(SPHINXBUILD) api/ -b man $(ALLSPHINXOPTS) $(APIBUILDDIR)
@echo
- @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+ @echo "Build finished. The manual pages are in $(DOCSBUILDDIR)/man."
+ @echo "Build finished. The manual pages are in $(APIBUILDDIR)/man."
texinfo:
- $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ $(SPHINXBUILD) docs/ -b texinfo $(ALLSPHINXOPTS) $(DOCSBUILDDIR)
+ $(SPHINXBUILD) api/ -b texinfo $(ALLSPHINXOPTS) $(APIBUILDDIR)
@echo
- @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+ @echo "Build finished. The Texinfo files are in
$(DOCSBUILDDIR)/texinfo."
+ @echo "Build finished. The Texinfo files are in $(APIBUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info:
- $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ $(SPHINXBUILD) docs/ -b texinfo $(ALLSPHINXOPTS) $(DOCSBUILDDIR)
+ $(SPHINXBUILD) api/ -b texinfo $(ALLSPHINXOPTS) $(APIBUILDDIR)
@echo "Running Texinfo files through makeinfo..."
- make -C $(BUILDDIR)/texinfo info
- @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+ make -C $(DOCSBUILDDIR)/texinfo info
+ make -C $(APIBUILDDIR)/texinfo info
+ @echo "makeinfo finished; the Info files are in
$(DOCSBUILDDIR)/texinfo."
+ @echo "makeinfo finished; the Info files are in $(APIBUILDDIR)/texinfo."
gettext:
- $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+ $(SPHINXBUILD) docs/ -b gettext $(I18NSPHINXOPTS) $(DOCSBUILDDIR)
+ $(SPHINXBUILD) api/ -b gettext $(I18NSPHINXOPTS) $(APIBUILDDIR)
@echo
- @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+ @echo "Build finished. The message catalogs are in
$(DOCSBUILDDIR)/locale."
+ @echo "Build finished. The message catalogs are in
$(APIBUILDDIR)/locale."
changes:
- $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+ $(SPHINXBUILD) docs/ -b changes $(ALLSPHINXOPTS) $(DOCSBUILDDIR)
+ $(SPHINXBUILD) api/ -b changes $(ALLSPHINXOPTS) $(APIBUILDDIR)
@echo
- @echo "The overview file is in $(BUILDDIR)/changes."
+ @echo "The overview file is in $(DOCSBUILDDIR)/changes."
+ @echo "The overview file is in $(APIBUILDDIR)/changes."
linkcheck:
- $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+ $(SPHINXBUILD) docs/ -b linkcheck $(ALLSPHINXOPTS) $(DOCSBUILDDIR)
+ $(SPHINXBUILD) api/ -b linkcheck $(ALLSPHINXOPTS) $(APIBUILDDIR)
@echo
@echo "Link check complete; look for any errors in the above output " \
- "or in $(BUILDDIR)/linkcheck/output.txt."
+ "or in $(APIBUILDDIR)/linkcheck/output.txt."
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in $(DOCSBUILDDIR)/linkcheck/output.txt."
+
doctest:
- $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+ $(SPHINXBUILD) docs/ -b doctest $(ALLSPHINXOPTS) $(DOCSBUILDDIR)
+ $(SPHINXBUILD) api/ -b doctest $(ALLSPHINXOPTS) $(APIBUILDDIR)
@echo "Testing of doctests in the sources finished, look at the " \
- "results in $(BUILDDIR)/doctest/output.txt."
+ "results in $(APIBUILDDIR)/doctest/output.txt."
+ @echo "Testing of doctests in the sources finished, look at the " \
+ "results in $(DOCSBUILDDIR)/doctest/output.txt."
+
xml:
- $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+ $(SPHINXBUILD) docs/ -b xml $(ALLSPHINXOPTS) $(DOCSBUILDDIR)
+ $(SPHINXBUILD) api/ -b xml $(ALLSPHINXOPTS) $(APIBUILDDIR)
@echo
- @echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+ @echo "Build finished. The XML files are in $(DOCSBUILDDIR)/xml."
+ @echo "Build finished. The XML files are in $(APIBUILDDIR)/xml."
pseudoxml:
- $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+ $(SPHINXBUILD) api/ -b pseudoxml $(ALLSPHINXOPTS) $(APIBUILDDIR)
+ $(SPHINXBUILD) docs/ -b pseudoxml $(ALLSPHINXOPTS) $(DOCSBUILDDIR)
@echo
- @echo "Build finished. The pseudo-XML files are in
$(BUILDDIR)/pseudoxml."
+ @echo "Build finished. The pseudo-XML files are in
$(DOCSBUILDDIR)/pseudoxml."
+ @echo "Build finished. The pseudo-XML files are in
$(APIBUILDDIR)/pseudoxml."
diff --git a/api-bank.rst b/api/api-bank.rst
similarity index 100%
rename from api-bank.rst
rename to api/api-bank.rst
diff --git a/api-common.rst b/api/api-common.rst
similarity index 99%
rename from api-common.rst
rename to api/api-common.rst
index 411f7df..defabe6 100644
--- a/api-common.rst
+++ b/api/api-common.rst
@@ -455,7 +455,8 @@ Any piece of signed data, complies to the abstract data
structure given below.
The following list contains all the data structure that can be signed in
Taler. Their definition is typically found in `src/include/taler_signatures.h`,
-within the :ref:`exchange's codebase <exchange-repo>`.
+within the
+`exchange's codebase
<https://docs.taler.net/global-licensing.html#exchange-repo>`_.
.. _TALER_WithdrawRequestPS:
.. sourcecode:: c
diff --git a/api-error.rst b/api/api-error.rst
similarity index 100%
rename from api-error.rst
rename to api/api-error.rst
diff --git a/api-exchange.rst b/api/api-exchange.rst
similarity index 99%
rename from api-exchange.rst
rename to api/api-exchange.rst
index 20f7178..a0c2368 100644
--- a/api-exchange.rst
+++ b/api/api-exchange.rst
@@ -20,7 +20,8 @@ The Exchange RESTful JSON API
=============================
The API specified here follows the :ref:`general conventions <http-common>`
-for all details not specified in the individual requests. The :ref:`glossary`
+for all details not specified in the individual requests.
+The `glossary <https://docs.taler.net/glossary.html#glossary>`
defines all specific terms used in this section.
.. _keys:
@@ -72,7 +73,7 @@ possibly by using HTTPS.
// The exchange's signing keys.
signkeys: SignKey[];
- // compact EdDSA signature_ (binary-only) over the SHA-512 hash of the
+ // compact EdDSA `signature`_ (binary-only) over the SHA-512 hash of the
// concatenation of all SHA-512 hashes of the RSA denomination public
keys
// in `denoms` in the same order as they were in `denoms`. Note that for
// hashing, the binary format of the RSA public keys is used, and not
their
diff --git a/api-merchant.rst b/api/api-merchant.rst
similarity index 96%
rename from api-merchant.rst
rename to api/api-merchant.rst
index 9eccc2f..70ab906 100644
--- a/api-merchant.rst
+++ b/api/api-merchant.rst
@@ -23,7 +23,9 @@
Merchant API
============
-Before reading the API reference documentation, see the :ref:`merchant
architecture<merchant-arch>` and :ref:`payprot`
+Before reading the API reference documentation, see the
+`merchant architecture
<https://docs.taler.net/dev-merchant.html#merchant-arch>`_
+and the `payment protocol
<https://docs.taler.net/integration-merchant.html#payprot>`_
---------------------
The Frontend HTTP API
@@ -77,7 +79,8 @@ This frontend API is non-normative, and only gives an example
of what a typical
// maximum fees merchant agreed to cover as per the contract
max_fee: Amount;
- // The `merchant instance <instances-lab>`_ which is going to receive
the final wire transfer.
+ // The `merchant instance
<https://docs.taler.net/operate-merchant.html#instances-lab>`_
+ // which is going to receive the final wire transfer.
instance: string;
// Signature of `TALER_ContractPS`_
@@ -139,8 +142,8 @@ This frontend API is non-normative, and only gives an
example of what a typical
Returns a cooperative merchant page (called the execution page) that will
send the ``taler-execute-payment`` to the wallet and react to failure or
success of the actual payment. ``fulfillment_url`` is included in the
`contract`_.
- Furthermore, :ref:`payprot` documents the payment protocol between wallets
and
- merchants.
+ Furthermore, `<https://docs.taler.net/integration-merchant.html#payprot>`_
+ documents the payment protocol between wallets and merchants.
The wallet will inject an ``XMLHttpRequest`` request to the merchant's
``$pay_url`` in the context of the execution page. This mechanism is
@@ -262,7 +265,7 @@ The following API are made available by the merchant's
`backend` to the merchant
:query wtid: raw wire transfer identifier identifying the wire transfer (a
base32-encoded value)
:query exchange: base URI of the exchange that made the wire transfer
- :query instance: (optional) identificative token of the merchant
:ref:`instance <instances-lab>` which is being tracked.
+ :query instance: (optional) identificative token of the merchant `instance
<https://docs.taler.net/operate-merchant.html#instances-lab>`_ which is being
tracked.
**Response:**
@@ -330,7 +333,7 @@ The following API are made available by the merchant's
`backend` to the merchant
**Request:**
:query id: ID of the transaction we want to trace (an integer)
- :query instance: identificative token for the merchant instance which is to
be tracked (optional). See :ref:`instances-lab`. This information is needed
because the request has to be signed by the merchant, thus we need to pick the
instance's private key.
+ :query instance: identificative token for the merchant instance which is to
be tracked (optional). See
`<https://docs.taler.net/operate-merchant.html#instances-lab>`_. This
information is needed because the request has to be signed by the merchant,
thus we need to pick the instance's private key.
**Response:**
diff --git a/conf.py b/api/conf.py
similarity index 100%
copy from conf.py
copy to api/conf.py
diff --git a/api/exts/__pycache__/tsref.cpython-35.pyc
b/api/exts/__pycache__/tsref.cpython-35.pyc
new file mode 100644
index 0000000..f8474d5
Binary files /dev/null and b/api/exts/__pycache__/tsref.cpython-35.pyc differ
diff --git a/exts/tsref.py b/api/exts/tsref.py
similarity index 100%
copy from exts/tsref.py
copy to api/exts/tsref.py
diff --git a/index.rst b/api/index.rst
similarity index 65%
copy from index.rst
copy to api/index.rst
index 6de1dbd..9e49818 100644
--- a/index.rst
+++ b/api/index.rst
@@ -41,40 +41,6 @@ In this document, we describe the REST-based APIs between
the various
components, internal architecture of key components, and how to get them
installed.
------------------
-Operator Handbook
------------------
-
-The *Operator Handbook* is for people who want to run a exchange or a merchant.
-It focuses on how to install, configure and run the required software.
-
-.. toctree::
- :maxdepth: 2
-
- global_licensing
- configuration-basics
- operate-exchange
- operate-merchant
- versioning
-
-------------------------
-Web Integration Handbook
-------------------------
-
-The *Web Integration Handbook* is for those who want to interact with Taler
-wallets on their own website. Integrators will also have to be familiar with
-the material covered in the *Operator Handbook*.
-
-
-.. toctree::
- :maxdepth: 2
-
- integration-general
- integration-bank
- integration-merchant
- example-essay-store
-
-
--------------------------------------
Taler HTTP Core Protocol Specification
--------------------------------------
@@ -92,33 +58,3 @@ interfaces between the core components of Taler.
api-bank
wireformats
-
-
-------------------
-Developer Handbook
-------------------
-
-The *Developer Handbook* brings developers up to speed who want to hack on the
-core components of the Taler reference implementation.
-
-.. toctree::
- :maxdepth: 2
-
- dev-talerdotnet
- dev-wallet-wx
- dev-exchange
- dev-merchant
- deployment.rst
- releases.rst
-
-------------------
-Indices and tables
-------------------
-
-.. toctree::
- :hidden:
-
- glossary
-
-* :doc:`glossary`
-* :ref:`search`
diff --git a/wireformats.rst b/api/wireformats.rst
similarity index 100%
rename from wireformats.rst
rename to api/wireformats.rst
diff --git a/conf.py b/docs/conf.py
similarity index 100%
rename from conf.py
rename to docs/conf.py
diff --git a/configuration-basics.rst b/docs/configuration-basics.rst
similarity index 100%
rename from configuration-basics.rst
rename to docs/configuration-basics.rst
diff --git a/deployment.rst b/docs/deployment.rst
similarity index 100%
rename from deployment.rst
rename to docs/deployment.rst
diff --git a/dev-exchange.rst b/docs/dev-exchange.rst
similarity index 100%
rename from dev-exchange.rst
rename to docs/dev-exchange.rst
diff --git a/dev-merchant.rst b/docs/dev-merchant.rst
similarity index 100%
rename from dev-merchant.rst
rename to docs/dev-merchant.rst
diff --git a/dev-talerdotnet.rst b/docs/dev-talerdotnet.rst
similarity index 100%
rename from dev-talerdotnet.rst
rename to docs/dev-talerdotnet.rst
diff --git a/dev-wallet-wx.rst b/docs/dev-wallet-wx.rst
similarity index 100%
rename from dev-wallet-wx.rst
rename to docs/dev-wallet-wx.rst
diff --git a/example-essay-store.rst b/docs/example-essay-store.rst
similarity index 64%
rename from example-essay-store.rst
rename to docs/example-essay-store.rst
index dc0f3f1..14cb31d 100644
--- a/example-essay-store.rst
+++ b/docs/example-essay-store.rst
@@ -21,7 +21,7 @@ Example: Essay Store
====================
This section shows how to set up a merchant :ref:`frontend <merchant-arch>`,
and is
-inspired by our demonstration shop running at `https://blog.demo.taler.net/`.
+inspired by our demonstration shop running at `https://shop.demo.taler.net/`.
It is recommended that the reader is already familiar with the
:ref:`payment protocol and terminology <payprot>`.
@@ -29,88 +29,112 @@ The code we are going to describe is available at
https://git.taler.net/merchant-frontends.git/tree/talerfrontends/blog
and is implemented in Python+Flask.
-The frontend shows a list of buyable articles in its homepage, and once the
-user clicks one of them, they will either get the Taler :ref:`contract
<contract>`
-or a credit card paywall if they don't have the Taler wallet.
+The desired effect is the homepage showing a list of buyable articles, and
once the
+user clicks one of them, they will either get the Taler
+`contract <https://api.taler.net/api-merchnat.html#contract>`_
+or a credit card paywall if they have no Taler wallet installed.
Each article thus links to a `offer URL`, whose layout is shown below.
`https://shop.demo.taler.net/essay/Appendix_A:_A_Note_on_Software`
Once the server side logic receives a request for a offer URL, it needs to
-instruct the browser to retrieve a Taler contract. This action can be taken
-either with or without JavaScript, see the next section.
+instruct the wallet to retrieve a Taler contract. This action can be taken
+either with or **without** the use of JavaScript, see the next section.
-----------------------
Triggering the contract
-----------------------
+It is important to note that the contract is not returned simply
+as the offer URL's response, but rather the frontend `instructs`
+the browser on how to retrieve the contract. That is needed for
+the right handling of the cases where the wallet is not installed.
+
.. note::
- The code samples shown below are intentionally incomplete, as often
+ The code samples shown below are intentionally "incomplete", as often
one function contains logic for multiple actions. Thus in order to not
mix concepts form different actions under one section, parts of code not
related to the section being documented have been left out.
**With JavaScript**
-We return a HTML page, whose template is in
-``talerfrontends/blog/templates/purchase.html``, that imports
``taler-wallet-lib.js``,
-so that the function ``taler.offerContractFrom()`` can be invoked into the
user's
+In this case, the objective is to call the function
``taler.offerContractFrom()`` into the user browser, which will then retrieve
the
+contract. In order to do that, we return a HTML page, whose
+template is in ``talerfrontends/blog/templates/purchase.html``,
+that imports ``taler-wallet-lib.js``, so that the function
+``taler.offerContractFrom()`` can be invoked into the user's
browser.
The server side handler for a offer URL needs to render ``purchase.html`` by
passing
the right parameters to ``taler.offerContractFrom()``.
The rendering is done by the ``article`` function at
``talerfrontends/blog/blog.py``,
-and looks like the following sample.
+and is done by Flask's ``render_template()``, see below.
.. sourcecode:: python
- return render_template('templates/purchase.html',
- article_name=name,
- no_contract=1,
- contract_url=quote(contract_url),
- data_attribute="data-taler-contractoffer=%s" %
contract_url)
+ # 'name' is the article name, and is set to the right value
+ # by Flask
+ # The 'data' parameter is used to send images along
+ # the articles, however its use is beyond the scope of
+ # this survey.
+ def article(name, data=None):
+ ...
+ ...
+
+ return render_template('templates/purchase.html',
+ article_name=name,
+ no_contract=1,
+ contract_url=quote(contract_url),
+ data_attribute="data-taler-contractoffer=%s" %
contract_url)
After the rendering, (part of) ``purchase.html`` will look like shown below.
.. sourcecode:: html
- ...
- <script src="/static/web-common/taler-wallet-lib.js"
type="application/javascript"></script>
- <script src="/static/purchase.js" type="application/javascript"></script>
- ...
- <meta name="contract_url"
value="https://shop.demo.taler.net/generate-contract?article_name=Appendix_A:_A_Note_on_Software";>
-
- ...
- ...
-
- <div id="ccfakeform" class="fade">
- <p>
- Oops, it looks like you don't have a Taler wallet installed. Why don't
you enter
- all your credit card details before reading the article? <em>You can also
- use GNU Taler to complete the purchase at any time.</em>
- </p>
-
- <form>
- First name<br> <input type="text"></input><br>
- Family name<br> <input type="text"></input><br>
- Age<br> <input type="text"></input><br>
- Nationality<br> <input type="text"></input><br>
- Gender<br> <input type="radio" name"gender">Male</input>
- CC number<br> <input type="text"></input><br>
- <input type="radio" name="gender">Female</input><br>
- </form>
- <form method="get" action="/cc-payment/{{ article_name }}">
- <input type="submit"></input>
- </form>
- </div>
+ <html>
+ <head>
+ <!-- ... -->
+ <script src="/static/web-common/taler-wallet-lib.js"
type="application/javascript"></script>
+ <script src="/static/purchase.js" type="application/javascript"></script>
+ <!-- ... -->
+ <meta name="contract_url"
value="https://shop.demo.taler.net/generate-contract?article_name=Appendix_A:_A_Note_on_Software";>
+
+ </head>
+ <body>
+ <!-- ... -->
+ <!-- ... -->
- <div id="talerwait">
- <em>Processing payment with GNU Taler, please wait <span
id="action-indicator"></span></em>
- </div>
- ...
+ <div id="ccfakeform" class="fade">
+ <p>
+ Oops, it looks like you don't have a Taler wallet installed. Why
don't you enter
+ all your credit card details before reading the article? <em>You can
also
+ use GNU Taler to complete the purchase at any time.</em>
+ </p>
+ <form>
+ First name<br> <input type="text"></input><br>
+ Family name<br> <input type="text"></input><br>
+ Age<br> <input type="text"></input><br>
+ Nationality<br> <input type="text"></input><br>
+ Gender<br> <input type="radio" name="gender">Male</input>
+ CC number<br> <input type="text"></input><br>
+ <input type="radio" name="gender">Female</input><br>
+ </form>
+
+ <form method="get" action="/cc-payment/{{ article_name }}">
+ <input type="submit"></input>
+ </form>
+ </div>
+
+ <div id="talerwait">
+ <em>Processing payment with GNU Taler, please wait <span
id="action-indicator"></span></em>
+ </div>
+ <!-- ... -->
+ </body>
+ </html>
+
The script ``purchase.js`` is now in charge of implementing the behaviour we
seek.
It needs to register two handlers: one called whenever the wallet is detected
in the
@@ -133,7 +157,9 @@ message and uncover the credit card pay form. See below.
.. sourcecode:: javascript
function handleWalletAbsent() {
+ // Hide "please wait" message
document.getElementById("talerwait").style.display = "none";
+ // Uncover credit card pay form
document.body.style.display = "";
}
@@ -144,12 +170,17 @@ contract URL from the responsible ``meta`` tag, and
finally invoke ``taler.offer
.. sourcecode:: javascript
function handleWalletPresent() {
+ // Hide credit card paywall
document.getElementById("ccfakeform").style.display = "none";
+ // Show "please wait" message
document.getElementById("talerwait").style.display = "";
...
...
// Fetch contract URL from 'meta' tag.
let contract_url = document.querySelectorAll("[name=contract_url]")[0];
+ // If this call is successful, it will obtain the contract,
+ // hand it to the wallet, so the wallet can eventually
+ // show it to the user.
taler.offerContractFrom(decodeURIComponent(contract_url.getAttribute("value")));
...
}
@@ -175,12 +206,20 @@ response.
.. sourcecode:: python
- ...
- # Create response.
- response = make_response(render_template('templates/fallback.html'), 402)
- # Set "X-Taler-Contract-Url" header to the contract's URL.
- response.headers["X-Taler-Contract-Url"] = contract_url
- return response
+ # 'name' is the article name, and is set to the right value
+ # by Flask
+ # The 'data' parameter is used to send images along
+ # the articles, however its use is beyond the scope of
+ # this survey.
+ def article(name, data=None):
+ ...
+ ...
+
+ # Create response.
+ response = make_response(render_template('templates/fallback.html'), 402)
+ # Set "X-Taler-Contract-Url" header to the contract's URL.
+ response.headers["X-Taler-Contract-Url"] = contract_url
+ return response
The ``make_response`` function is exported by Flask, so it's beyond the scope
of this document to explain it; however, it returns a "response object" having
@@ -191,10 +230,11 @@ not installed, the browser would keep that page shown.
``contract_url`` is defined in the earlier steps of the same function; however,
in this example it looks like:
-``https://shop.demo.taler.net/essay/generate-contract?article_name=Appendix_A:_A_Note_on_Software``.
-The next task for this frontend is generating and returning the contract.
-That is accomplished by the function ``generate_contract``, defined in
+
`https://shop.demo.taler.net/essay/generate-contract?article_name=Appendix_A:_A_Note_on_Software`.
+
+The frontend will also have to provide the contract. That is done
+by the handler ``generate_contract``, defined in
``talerfrontends/blog/blog.py``. See below.
.. sourcecode:: python
@@ -209,19 +249,21 @@ That is accomplished by the function
``generate_contract``, defined in
return jsonify(**contract_resp)
-Its task is then to provide the ``make_contract`` subroutine all the
+Its task is to feed the ``make_contract`` subroutine with all the
values it needs to generate a contract. Those values are: the timestamp
for the contract, the transaction ID, and the article name; respectively,
``now``, ``tid``, and ``article_name``.
After ``make_contract`` returns, the variable ``contract`` will hold a
-`dict` type that complies with a contract :ref:`proposition <proposition>`.
+`dict` type that complies with a contract
+`proposition <https://api.taler.net/api-merchnat.html#proposition>`_
We then call ``sign_contract`` feeding it with the proposition, so that
it can forward it to the backend and return it signed. Finally we return
-the signed proposition, complying with the :ref:`Offer <contract>` object.
+the signed proposition, complying with the
+`Offer <https://api.taler.net/api-merchant.html#contract>`_ object.
-For simplicity, any article costs the same price, so no database operation
-is required to create the proposition.
+For simplicity, any article costs the same price, so the frontend
+doesn't need to map articles to prices.
Both ``make_contract`` and ``sign_contract`` are defined in
``talerfrontends/blog/helpers.py``.
@@ -240,31 +282,37 @@ will firstly check that:
.. sourcecode:: python
+ # 'name' is the article name, and is set to the right value
+ # by Flask
+ # The 'data' parameter is used to send images along
+ # the articles, however its use is beyond the scope of
+ # this survey.
def article(name, data=None):
# Get list of payed articles from the state
payed_articles = session.get("payed_articles", [])
if name in payed_articles:
...
- # This statement ends the successful case.
+ # The articles has been paid, so return it to the
+ # customer.
return send_file(get_article_file(article))
...
In case the article has not been paid yet, the fulfillment handler needs
to `reconstruct` the contract, in order to get a precise reference about the
-purchase in progress.
+purchase in being served.
All the information needed to reconstruct the contract is contained in the
-fulfillment URL parameters; the URL layout is as follows:
+fulfillment URL parameters. See below the URL layout:
`https://shop.demo.taler.net/essay/Appendix_A:_A_Note_on_Software?uuid=<CONTRACT-HASHCODE>×tamp=<TIMESTAMP>tid=<TRANSACTION_ID>`
The way the contract is reconstructed is exactly the same as it was generated
in the previous steps: we need to call ``make_contract`` to get the original
-:ref:`proposition <proposition>` and then ``sign_contract``. Recall that aside
-from allowing the backend to add missing fields to the proposition,
``sign_contract``
-returns the contract hashcode also, that we should compare with the ``uuid``
-parameter given by the wallet as a URL parameter.
+`proposition <https://api.taler.net/api-merchnat.html#proposition>`_ and then
+``sign_contract``. Recall that aside from allowing the backend to add missing
+fields to the proposition, ``sign_contract`` returns the contract hashcode
also,
+that we should compare with the ``uuid`` parameter provided by the wallet.
In our blog, all the fulfillment logic is implemented in the function
``article``,
defined in ``talerfrontends/blog/blog.py``. It is important to note that this
@@ -273,29 +321,36 @@ URL design allows it, it is not mandatory to split up
things. In our example, t
offer URL differs from the fulfillment URL respect to the number (and type) of
parameters, so the ``article`` function can easily decide whether it has to
handle
a "offer" or a "fulfillment" case. See below how the function detects the
right
-case and reconstruct the contract.
+case and reconstructs the contract.
.. sourcecode:: python
- ...
- hc = request.args.get("uuid")
- tid_str = request.args.get("tid")
- timestamp_str = request.args.get("timestamp")
- if hc is None or tid_str is None or timestamp_str is None:
- contract_url = make_url("/generate-contract", ("article_name",name))
- ... # Go on operating the offer URL and return
-
- # Operate fulfillment URL
- try:
- tid = int(tid_str)
- except ValueError:
- raise MalformedParameterError("tid")
- try:
- timestamp = int(timestamp_str)
- except ValueError:
- raise MalformedParameterError("timestamp")
-
- # 'name' is the article name, and is set to the right value by Flask
+ # 'name' is the article name, and is set to the right value
+ # by Flask
+ # The 'data' parameter is used to send images along
+ # the articles, however its use is beyond the scope of
+ # this survey.
+ def article(name, data=None):
+
+ ...
+ hc = request.args.get("uuid")
+ tid_str = request.args.get("tid")
+ timestamp_str = request.args.get("timestamp")
+ if hc is None or tid_str is None or timestamp_str is None:
+ # Offer URL case.
+ contract_url = make_url("/generate-contract", ("article_name",name))
+ ... # Go on operating the offer URL and return
+
+ # Fulfillment URL case from here on.
+ try:
+ tid = int(tid_str)
+ except ValueError:
+ raise MalformedParameterError("tid")
+ try:
+ timestamp = int(timestamp_str)
+ except ValueError:
+ raise MalformedParameterError("timestamp")
+
restored_contract = make_contract(article_name=name, tid=tid,
timestamp=timestamp)
contract_resp = sign_contract(restored_contract)
@@ -333,13 +388,23 @@ See below how the function ``article`` does the rendering.
.. sourcecode:: python
- return render_template('templates/purchase.html',
- hc=hc,
- pay_url=quote(pay_url),
- offering_url=quote(offering_url),
- article_name=name,
- no_contract=0,
- data_attribute="data-taler-executecontract=%s,%s,%s"
% (hc, pay_url, offering_url))
+ # 'name' is the article name, and is set to the right value
+ # by Flask
+ # The 'data' parameter is used to send images along
+ # the articles, however its use is beyond the scope of
+ # this survey.
+ def article(name, data=None):
+
+ ...
+ ...
+
+ return render_template('templates/purchase.html',
+ hc=hc,
+ pay_url=quote(pay_url),
+ offering_url=quote(offering_url),
+ article_name=name,
+ no_contract=0,
+
data_attribute="data-taler-executecontract=%s,%s,%s" % (hc, pay_url,
offering_url))
After the rendering, (part of) ``purchase.html`` will look like shown below.
@@ -387,9 +452,10 @@ That is done with:
.. note::
- So far, the template and script code are exactly the same as the offer URL
case,
- since we use them for both cases: see below how the script distinguishes
offer
- from fulfillment case.
+ So far, the template and the imported script (``purchase.js``)
+ are exactly the same as the offer URL case, since we use them
+ for both cases. See below how the script distinguishes "offer"
+ from "fulfillment" case.
Note that the ``taler`` object is exported by ``taler-wallet-lib.js``, and
contains all
is needed to communicate with the wallet.
@@ -401,7 +467,9 @@ message and uncover the credit card pay form. See below.
.. sourcecode:: javascript
function handleWalletAbsent() {
+ // Hide "please wait" message
document.getElementById("talerwait").style.display = "none";
+ // Uncover credit card pay form
document.body.style.display = "";
}
@@ -415,19 +483,22 @@ useless, as it is highly unlikely that the wallet is not
installed.
.. sourcecode:: javascript
function handleWalletPresent() {
+ // Hide the credit card pay form
document.getElementById("ccfakeform").style.display = "none";
+ // Show "please wait" message
document.getElementById("talerwait").style.display = "";
// The `no_contract` value is provided by the function `article` via a
// 'meta' tag in the template. When this value equals 1, then we are in
the
- // "offer URL" case, otherwise we are in the "fulfillment URL" case.
+ // "offer" URL case, otherwise we are in the "fulfillment" URL case.
let no_contract = document.querySelectorAll("[name=no_contract]")[0];
if (Number(no_contract.getAttribute("value"))) {
+ // "Offer" case
let contract_url = document.querySelectorAll("[name=contract_url]")[0];
taler.offerContractFrom(decodeURIComponent(contract_url.getAttribute("value")));
}
else {
- // Fulfillment case.
+ // "Fulfillment" case.
let hc = document.querySelectorAll("[name=hc]")[0];
let pay_url = document.querySelectorAll("[name=pay_url]")[0];
let offering_url = document.querySelectorAll("[name=offering_url]")[0];
@@ -437,8 +508,8 @@ useless, as it is highly unlikely that the wallet is not
installed.
}
}
-Once the browser executes ``taler.executePayment()``, the wallet will send the
coins
-to ``pay_url``. Once the payment succeeds, the wallet will again visits the
+Once the browser executes ``taler.executePayment(...)``, the wallet will send
the coins
+to ``pay_url``. Once the payment succeeds, the wallet will again visit the
fulfillment URL, this time getting the article thanks to the "payed" status
set by
the ``pay_url`` handler.
@@ -451,7 +522,7 @@ Required" HTTP status code, along with the HTTP headers
``X-Taler-Contract-Hash`
..
FIXME:
- Are those three parameters anywhere, at least 'kindof' introduced?
+ Are those three parameters previously introduced?
Upon returning such a response, the wallet will automatically send the
payment to the URL indicated in ``X-Taler-Pay-Url``.
@@ -461,11 +532,22 @@ response.
.. sourcecode:: python
- response = make_response(render_template('templates/fallback.html'), 402)
- response.headers["X-Taler-Contract-Hash"] = hc
- response.headers["X-Taler-Pay-Url"] = pay_url
- response.headers["X-Taler-Offer-Url"] = offering_url
- return response
+ # 'name' is the article name, and is set to the right value
+ # by Flask
+ # The 'data' parameter is used to send images along
+ # the articles, however its use is beyond the scope of
+ # this survey.
+ def article(name, data=None):
+ ...
+
+ # 'make_response' is exported by Flask. It returns a
+ # "response object" with customizable status code, HTTP
+ # headers and body
+ response = make_response(render_template('templates/fallback.html'), 402)
+ response.headers["X-Taler-Contract-Hash"] = hc
+ response.headers["X-Taler-Pay-Url"] = pay_url
+ response.headers["X-Taler-Offer-Url"] = offering_url
+ return response
The template ``fallback.html`` contains the credit card pay form, which will be
used in the rare case where the wallet would not be detected in a fulfillment
@@ -478,8 +560,8 @@ Pay logic
---------
The pay handler for the blog is implemented by the function
-``pay`` at ``talerfrontends/blog/blog.py``. Its main duty is
-to receive the :ref:`deposit permission <DepositPermission>`
+``pay`` at ``talerfrontends/blog/blog.py``. Its main duty is to receive the
+`deposit permission
<https://api.taler.net/api-merchant.html#DepositPermission>`_
from the wallet, forward it to the backend, and return the outcome
to the wallet. See below the main steps of its implementation.
@@ -524,18 +606,16 @@ to the wallet. See below the main steps of its
implementation.
if 200 != r.status_code:
raise BackendError(r.status_code, r.text)
- # The payment went through. Now set the state as "payed"
- # and return 200 OK.
+ # The payment went through..
...
# Resume the article name
article = si["article_name"]
- # We keep a *list* of articles the customer can currently
- # read
+ # Set the article's state as "payed". This is realized by
+ # appending it to a *list* of articles the customer is currently
+ # allowed to read.
payed_articles = session["payed_articles"] =
session.get("payed_articles", [])
-
- # Add the article name among the ones that were already paid
if article not in payed_articles:
payed_articles.append(article)
diff --git a/exchange-db-generate.sh b/docs/exchange-db-generate.sh
similarity index 100%
rename from exchange-db-generate.sh
rename to docs/exchange-db-generate.sh
diff --git a/exchange-db.png b/docs/exchange-db.png
similarity index 100%
rename from exchange-db.png
rename to docs/exchange-db.png
diff --git a/docs/exts/__pycache__/tsref.cpython-35.pyc
b/docs/exts/__pycache__/tsref.cpython-35.pyc
new file mode 100644
index 0000000..abc92f0
Binary files /dev/null and b/docs/exts/__pycache__/tsref.cpython-35.pyc differ
diff --git a/exts/tsref.py b/docs/exts/tsref.py
similarity index 100%
rename from exts/tsref.py
rename to docs/exts/tsref.py
diff --git a/global_licensing.rst b/docs/global-licensing.rst
similarity index 100%
rename from global_licensing.rst
rename to docs/global-licensing.rst
diff --git a/glossary.rst b/docs/glossary.rst
similarity index 100%
rename from glossary.rst
rename to docs/glossary.rst
diff --git a/index.rst b/docs/index.rst
similarity index 88%
rename from index.rst
rename to docs/index.rst
index 6de1dbd..c24550b 100644
--- a/index.rst
+++ b/docs/index.rst
@@ -51,7 +51,7 @@ It focuses on how to install, configure and run the required
software.
.. toctree::
:maxdepth: 2
- global_licensing
+ global-licensing
configuration-basics
operate-exchange
operate-merchant
@@ -74,26 +74,6 @@ the material covered in the *Operator Handbook*.
integration-merchant
example-essay-store
-
---------------------------------------
-Taler HTTP Core Protocol Specification
---------------------------------------
-
-The *Protocol Specification* defines the HTTP-based, predominantly RESTful
-interfaces between the core components of Taler.
-
-.. toctree::
- :maxdepth: 2
-
- api-common
- api-error
- api-exchange
- api-merchant
- api-bank
-
- wireformats
-
-
------------------
Developer Handbook
------------------
@@ -108,8 +88,8 @@ core components of the Taler reference implementation.
dev-wallet-wx
dev-exchange
dev-merchant
- deployment.rst
- releases.rst
+ deployment
+ releases
------------------
Indices and tables
diff --git a/integration-bank.rst b/docs/integration-bank.rst
similarity index 100%
rename from integration-bank.rst
rename to docs/integration-bank.rst
diff --git a/integration-general.rst b/docs/integration-general.rst
similarity index 100%
rename from integration-general.rst
rename to docs/integration-general.rst
diff --git a/integration-merchant.rst b/docs/integration-merchant.rst
similarity index 66%
rename from integration-merchant.rst
rename to docs/integration-merchant.rst
index f322161..7cf9304 100644
--- a/integration-merchant.rst
+++ b/docs/integration-merchant.rst
@@ -203,113 +203,54 @@ parameters to the wallet, which will:
1. Send the payment to `<PAY-URL>` if `<CONTRACT-HASH>` is found in its
database (meaning that the user accepted it).
2. Redirect the browser to `<OFFER-URL>`, if `<CONTRACT-HASH>` is NOT found in
its database, meaning that the user visited a shared fulfillment URL.
---------------------
-Example: Essay Store
---------------------
-
-This section is a high-level description of a merchant :ref:`frontend
<merchant-arch>`,
-and is inspired by our demonstration essay store running at
`https://blog.demo.taler.net/`.
-Basically, it tells how the frontend reacts to clients visiting `offer` and
`fulfillment`
-URLs.
-
-The website is implemented in Python+Flask, and is available at
-https://git.taler.net/merchant-frontends.git/tree/talerfrontends/blog.
-
-The desired effect is that the homepage has a list of buyable articles, and
once the
-user clicks on one of them, they will either get the Taler :ref:`contract
<contract>`
-or a credit card paywall if they have no Taler wallet installed.
-
-In particular, any buyable article on the homepage links to an `offer URL`:
-
-.. sourcecode:: html
-
- <html>
- ...
- <h3><a href="/essay/How_to_write_a_frontend">How to write a
frontend</a></h3>
+..
+ ..................
+ State and security
+ ..................
+
+ The server-side state gets updated in two situations, (1) when an article is
+ "about" to be bought, which means when the user visits the fulfillment URL,
+ and (2) when the user actually pays. For (1), we use the contract hascode to
+ access the state, whereas in (2) we just define a list of payed articles.
+ For example:
+
+ .. sourcecode:: python
+
+ session[<HASHCODE>] = {'article_name': 'How_to_write_a_frontend'} # (1)
+ session['payed_articles'] = ['How_to_write_a_frontend',
'How_to_install_a_backend'] # (2)
+
+ The list of payed articles is used by the frontend to deliver the article to
the user:
+ if the article name is among ``session['payed_articles']``, then the user
gets what they
+ paid for.
+
+ The reason for using `<HASHCODE>` as the key is to prevent the wallet to
send bogus
+ parameters along the fulfillment URL. `<HASHCODE>` is the contract hashcode
that
+ the fulfillment handler gets from the backend using the fulfillment URL
parameters.
+
+ In fact, when the wallet sends the payment to the frontend pay handler, it
has to provide
+ both coins and contract hashcode. That hascode is (1) verified by the
backend when it
+ receives the coins, (2) used by the frontend to update the list of payed
articles.
+
+ See below an example of pay handler:
+
+ .. sourcecode:: python
+
...
- </html>
-
-whence the offer URL design is as follows::
-
- https://<BASEURL>/essay/<ARTICLE-NAME>
-
-`<ARTICLE-NAME>` is just a token that uniquely identifies the article within
the shop.
-
-The server-side handler for the offer URL will return a special page to the
client that
-will either HTTP GET the contract from the frontend, or show the credit card
paywall.
-See `above <offer>`_ how this special page works.
-
-It is interesting to note that the fulfillment URL is just the offer URL plus
-two additional parameters. It looks as follows::
-
-
https://<BASEURL>/essay/<ARTICLE-NAME>?tid=<TRANSACTION-ID>×tamp=<TIMESTAMP>
-
-.. note::
-
- Taler does not require that offer and fulfillment URL have this kind of
relationship.
- In fact, it is perfectly acceptable for the fulfillment URL to be hosted on
a different
- server under a different domain name.
-
-The fulfillment URL server-side handler implements the following logic: it
checks the state
-to see if `<ARTICLE-NAME>` has been payed, and if so, returns the article to
the user.
-If the user didn't pay, then it `executes` the contract by returning a special
page to the
-browser. The contract execution is the order to pay that the frontend gives to
the wallet.
-
-Basically, the frontend points the wallet to the hashcode of the contract
which is to be paid
-and the wallet responds by giving coins to the frontend. Because the frontend
doesn't perform
-any cryptographic work by design, it forwards `<ARTICLE-NAME>`,
`<TRANSACTION-ID>` and
-`<TIMESTAMP>` to the frontend in order to get the contract's hashcode.
-
-See `above <fulfillment>`_ for a detailed description of how the frontend
triggers the
-payment in the wallet.
-
-..................
-State and security
-..................
-
-The server-side state gets updated in two situations, (1) when an article is
-"about" to be bought, which means when the user visits the fulfillment URL,
-and (2) when the user actually pays. For (1), we use the contract hascode to
-access the state, whereas in (2) we just define a list of payed articles.
-For example:
-
-.. sourcecode:: python
-
- session[<HASHCODE>] = {'article_name': 'How_to_write_a_frontend'} # (1)
- session['payed_articles'] = ['How_to_write_a_frontend',
'How_to_install_a_backend'] # (2)
-
-The list of payed articles is used by the frontend to deliver the article to
the user:
-if the article name is among ``session['payed_articles']``, then the user gets
what they
-paid for.
-
-The reason for using `<HASHCODE>` as the key is to prevent the wallet to send
bogus
-parameters along the fulfillment URL. `<HASHCODE>` is the contract hashcode
that
-the fulfillment handler gets from the backend using the fulfillment URL
parameters.
-
-In fact, when the wallet sends the payment to the frontend pay handler, it has
to provide
-both coins and contract hashcode. That hascode is (1) verified by the backend
when it
-receives the coins, (2) used by the frontend to update the list of payed
articles.
-
-See below an example of pay handler:
-
-.. sourcecode:: python
-
- ...
-
- # 'deposit_permission' is the JSON object sent by the wallet
- # which contains coins and the contract hashcode.
- response = send_payment_to_backend(deposit_permission)
-
- # The backend accepted the payment
- if 200 == response.status_code:
- # Here we pick the article name from the state defined at
- # fulfillment time.
- # deposit_permission['H_contract'] is the contract hashcode
- payed_article = session[deposit_permission['H_contract']]['article_name']
- session['payed_articles'].append(payed_article)
-
-
-So the wallet is forced to send a valid contract hashcode along the payment,
-and since that hashcode is then used to update the list of payed articles,
-the wallet is forced to send fulfillment URL parameters that match that
hashcode,
-therefore being valid parameters.
+
+ # 'deposit_permission' is the JSON object sent by the wallet
+ # which contains coins and the contract hashcode.
+ response = send_payment_to_backend(deposit_permission)
+
+ # The backend accepted the payment
+ if 200 == response.status_code:
+ # Here we pick the article name from the state defined at
+ # fulfillment time.
+ # deposit_permission['H_contract'] is the contract hashcode
+ payed_article =
session[deposit_permission['H_contract']]['article_name']
+ session['payed_articles'].append(payed_article)
+
+
+ So the wallet is forced to send a valid contract hashcode along the payment,
+ and since that hashcode is then used to update the list of payed articles,
+ the wallet is forced to send fulfillment URL parameters that match that
hashcode,
+ therefore being valid parameters.
diff --git a/operate-exchange.rst b/docs/operate-exchange.rst
similarity index 97%
rename from operate-exchange.rst
rename to docs/operate-exchange.rst
index 874b837..38293bb 100644
--- a/operate-exchange.rst
+++ b/docs/operate-exchange.rst
@@ -106,12 +106,15 @@ For example, the utility may be invoked as follows::
Note that the value given to option `-t` must match the value in the JSON's
field ``"type"``.
-The generated file will be echoed by the exchange when serving :ref:`/wire
<wire-req>` requests.
+The generated file will be echoed by the exchange when serving
+`/wire <https://api.taler.net/api-exchange.html#wire-req>`_
+requests.
Outgoing
^^^^^^^^
-This exchange's bank account is used to give money to merchants, after
successful :ref:`deposits <deposit-par>`
+This exchange's bank account is used to give money to merchants, after
successful
+`deposits <https://api.taler.net/api-exchange.html#deposit-par>`_
operations. If `test` is the chosen wireformat, the outcoming bank account is
configured by the following
options under `[exchange-wire-outcoming-test]`:
diff --git a/operate-merchant.rst b/docs/operate-merchant.rst
similarity index 94%
rename from operate-merchant.rst
rename to docs/operate-merchant.rst
index 484d6eb..7f88a00 100644
--- a/operate-merchant.rst
+++ b/docs/operate-merchant.rst
@@ -88,7 +88,8 @@ pattern::
schema://hostname/
-`master_key` is the base32 encoding of the exchange's master key (see
:ref:`/keys <keys>`).
+`master_key` is the base32 encoding of the exchange's master key
+(see `/keys <https://api.taler.net/api-exchange.html#keys>`_).
In our demo, we use the following configuration::
[merchant-exchange-test]
@@ -180,18 +181,15 @@ instance `Tor` as follows::
[merchant-instance-wireformat-Tor]
TEST_RESPONSE_FILE = ${TALER_CONFIG_HOME}/merchant/wire/tor.json
-Please note that :ref:`Taler messagging<merchant-api>` is designed so that the
merchant
-frontend can instruct the backend on which instance has to be used in the
various operations.
-This information is optional, and if not given, the backend will act as the
`default` instance.
+Please note that `Taler messagging
<https://api.taler.net/api-merchant.html#merchant-api>`_
+is designed so that the merchant frontend can instruct the backend on which
instance has to
+be used in the various operations. This information is optional, and if not
given,
+the backend will act as the `default` instance.
++++++++++++
Installation
++++++++++++
-
-
-
-
In order to compile your merchant backend, you firstly need to install the GNU
Taler
exchange. As of other dependencies, the merchant backend needs exactly the
same ones
as the exchange does. Follow :ref:`those instructions <exchange-install>` to
build
diff --git a/releases.rst b/docs/releases.rst
similarity index 100%
rename from releases.rst
rename to docs/releases.rst
diff --git a/versioning.rst b/docs/versioning.rst
similarity index 100%
rename from versioning.rst
rename to docs/versioning.rst
--
To stop receiving notification emails like this one, please contact
address@hidden
- [GNUnet-SVN] [taler-api] branch master updated (ebb7bc5 -> 98909f9),
gnunet <=
- [GNUnet-SVN] [taler-api] 09/22: Appears?, gnunet, 2017/01/27
- [GNUnet-SVN] [taler-api] 02/22: fix link, gnunet, 2017/01/27
- [GNUnet-SVN] [taler-api] 06/22: Moving payment protocol on 'docs', gnunet, 2017/01/27
- [GNUnet-SVN] [taler-api] 10/22: Reverting previous (test) commit, gnunet, 2017/01/27
- [GNUnet-SVN] [taler-api] 12/22: fix link, gnunet, 2017/01/27
- [GNUnet-SVN] [taler-api] 16/22: Moving payment protocol on 'docs', gnunet, 2017/01/27
- [GNUnet-SVN] [taler-api] 05/22: Fix missing links, commenting out superfluous/outdated section, gnunet, 2017/01/27
- [GNUnet-SVN] [taler-api] 01/22: Proof-reading blog example page, gnunet, 2017/01/27
- [GNUnet-SVN] [taler-api] 19/22: Appears?, gnunet, 2017/01/27
- [GNUnet-SVN] [taler-api] 04/22: Still on splitting, gnunet, 2017/01/27