docs: new recommend path architecture documentation (digital-asset#4795)

CHANGELOG_BEGIN CHANGELOG_END
axman6 · Mar 9, 2020 · 0e046d9 · 0e046d9
1 parent e3c9f36
commit 0e046d9
Show file tree

Hide file tree

Showing 22 changed files with 525 additions and 405 deletions.
diff --git a/docs/configs/pdf/index.rst b/docs/configs/pdf/index.rst
@@ -35,16 +35,27 @@ Building applications
    :titlesonly:
    :maxdepth: 2
 
-   app-dev/index
-   daml-script/index
-   upgrade/index
+   app-dev/app-arch
+   app-dev/authentication
+   app-dev/ledger-api
    app-dev/bindings-java/index
    app-dev/bindings-scala/index
    app-dev/bindings-js
    app-dev/grpc/index
    app-dev/bindings-x-lang/index
-   app-dev/app-arch
-   app-dev/authentication
+   DAML Script <daml-script/index>
+   upgrade/index
+
+Deploying to DAML ledgers
+-------------------------
+
+.. toctree::
+   :titlesonly:
+   :maxdepth: 2
+
+   deploy/index
+   deploy/generic_ledger
+   deploy/ledger-topologies
 
 SDK tools
 ---------
@@ -67,14 +78,6 @@ Background concepts
    concepts/glossary
    concepts/ledger-model/index
 
-Deploying
----------
-
-.. toctree::
-   :titlesonly:
-   :maxdepth: 2
-
-   deploy/index
 
 Examples
 --------

diff --git a/docs/source/app-dev/app-arch.rst b/docs/source/app-dev/app-arch.rst
diff --git a/docs/source/app-dev/app-arch.rst.back b/docs/source/app-dev/app-arch.rst.back
diff --git a/docs/source/app-dev/authentication.rst b/docs/source/app-dev/authentication.rst
@@ -1,6 +1,8 @@
 .. Copyright (c) 2020 The DAML Authors. All rights reserved.
 .. SPDX-License-Identifier: Apache-2.0
 
+.. _authentication:
+
 Authentication
 ##############
 
@@ -13,10 +15,9 @@ To run your application against a :doc:`deployed ledger </deploy/index>`, you wi
 Introduction
 ************
 
-The main way for a DAML application to interact with a DAML ledger is through the :doc:`gRPC ledger API </app-dev/grpc/index>`.
-
-This API can be used to request changes to the ledger (e.g., "*Alice wants to exercise choice X on contract Y*),
-or to read data from the ledger (e.g., "*Alice wants to see all active contracts*").
+The :doc:`Ledger API </app-dev/ledger-api>` is used to request changes to the ledger (e.g., "*Alice
+wants to exercise choice X on contract Y*), or to read data from the ledger (e.g., "*Alice wants to
+see all active contracts*").
 
 What requests are valid is defined by :ref:`integrity <da-model-integrity>` and :ref:`privacy <da-model-privacy>` parts the :ref:`DA Ledger Model <da-ledgers>`.
 This model is defined in terms of :ref:`DAML parties <glossary-party>`,

diff --git a/docs/source/app-dev/bindings-java/index.rst b/docs/source/app-dev/bindings-java/index.rst
@@ -1,6 +1,8 @@
 .. Copyright (c) 2020 The DAML Authors. All rights reserved.
 .. SPDX-License-Identifier: Apache-2.0
 
+.. _java-bindings:
+
 Java bindings
 #############
 

diff --git a/docs/source/app-dev/bindings-scala/index.rst b/docs/source/app-dev/bindings-scala/index.rst
@@ -1,6 +1,8 @@
 .. Copyright (c) 2020 The DAML Authors. All rights reserved.
 .. SPDX-License-Identifier: Apache-2.0
 
+.. _scala-bindings:
+
 Scala bindings
 ##############
 

diff --git a/docs/source/app-dev/bindings-x-lang/index.rst b/docs/source/app-dev/bindings-x-lang/index.rst
@@ -6,20 +6,7 @@ Creating your own bindings
 
 This page gets you started with creating custom bindings for the Digital Asset distributed ledger.
 
-Introduction
-============
-
-Digital Asset currently provides bindings for the following programming languages:
-
-- :doc:`Java </app-dev/bindings-java/index>`
-
-- :doc:`Scala </app-dev/bindings-scala/index>`
-
-- :doc:`JavaScript (Node.js) </app-dev/bindings-js>`
-
-You can create bindings for any programming language supported by `gRPC <https://grpc.io/docs/>`_.
-
-What do we mean by "bindings"? Bindings for a language consist of two main components:
+Bindings for a language consist of two main components:
 
 - Ledger API
     Client "stubs" for the programming language, -- the remote API that allows sending ledger commands and receiving ledger transactions. You have to generate **Ledger API** from `the gRPC protobuf definitions in the daml repository on GitHub <https://github.com/digital-asset/daml/tree/master/ledger-api/grpc-definitions>`_. **Ledger API** is documented on this page: :doc:`/app-dev/grpc/index`. The `gRPC <https://grpc.io/docs/>`_ tutorial explains how to generate client "stubs".

diff --git a/docs/source/app-dev/developer_workflow.svg b/docs/source/app-dev/developer_workflow.svg
diff --git a/docs/source/app-dev/grpc/index.rst b/docs/source/app-dev/grpc/index.rst
@@ -1,8 +1,10 @@
 .. Copyright (c) 2020 The DAML Authors. All rights reserved.
 .. SPDX-License-Identifier: Apache-2.0
 
-The Ledger API using gRPC
-#########################
+.. _grpc:
+
+gRPC
+####
 
 .. toctree::
    :hidden:

diff --git a/docs/source/app-dev/index.rst → docs/source/app-dev/ledger-api.rst b/docs/source/app-dev/index.rst → docs/source/app-dev/ledger-api.rst
@@ -1,37 +1,23 @@
 .. Copyright (c) 2020 The DAML Authors. All rights reserved.
 .. SPDX-License-Identifier: Apache-2.0
 
-Writing applications using the Ledger API
-#########################################
+The Ledger API
+##############
 
 .. toctree::
    :hidden:
 
    services
    daml-lf-translation
 
-DAML contracts are stored on a ledger. In order to exercise choices on those contracts, create new ones, or read from the ledger, you need to use the **Ledger API**. (Every ledger that DAML can run on exposes this same API.) To write an application around a DAML ledger, you'll need to interact with the Ledger API from another language.
-
-Resources available to you
-**************************
-
-- **The Java bindings**: a library to help you write idiomatic applications using the Ledger API in Java.
-
-  :doc:`Read the documentation for the Java bindings </app-dev/bindings-java/index>`
-- **The experimental Node.js bindings**: a library to help you write idiomatic applications using the Ledger API in JavaScript. Information about the Node.js bindings isn't available in this documentation, but is on GitHub.
-
-  `Read the documentation for the Node.js bindings <http://www.github.com/digital-asset/daml-js>`__
-- **The underlying gRPC API**: if you want to interact with the ledger API from other languages, you'll need to use `gRPC <https://grpc.io>`__ directly.
-
-  :doc:`Read the documentation for the gRPC API </app-dev/grpc/index>`
-- **The application architecture guide**: this documentation gives high-level guidance on designing DAML Ledger applications.
-
-  :doc:`Read the application architecture guide </app-dev/app-arch>`
+To write an application around a DAML ledger, you'll need to interact with the **Ledger API** from
+another language. Every ledger that DAML can run on exposes this same API.
 
 What's in the Ledger API
 ************************
 
-No matter how you're accessing it (Java bindings, Node.js bindings, or gRPC), the Ledger API exposes the same services:
+You can access the Ledger API via via the HTTP JSON API, Java bindings, Scala bindings or gRPC. In
+all cases, the Ledger API exposes the same services:
 
 - Submitting commands to the ledger
 
@@ -74,7 +60,7 @@ As a user, you don't need to interact with DAML-LF directly. But inside the DAML
 When you need to know about DAML-LF
 ===================================
 
-DAML-LF is only really relevant when you're dealing with the objects you send to or receive from the ledger. If you use :doc:`code generation </app-dev/bindings-java/codegen>`, you don't need to know about DAML-LF at all, because this generates idiomatic representations of DAML for you.
+DAML-LF is only really relevant when you're dealing with the objects you send to or receive from the ledger. If you use any of the provided language bindings for the Ledger API, you don't need to know about DAML-LF at all, because this generates idiomatic representations of DAML for you.
 
 Otherwise, it can be helpful to know what the types in your DAML code look like at the DAML-LF level, so you know what to expect from the Ledger API.
 

diff --git a/docs/source/app-dev/recommended_architecture.svg b/docs/source/app-dev/recommended_architecture.svg
diff --git a/docs/source/concepts/glossary.rst b/docs/source/concepts/glossary.rst
@@ -307,7 +307,7 @@ Application, ledger client, integration
 
 **Application**, **ledger client** and **integration** are all terms for an application that sits on top of the `ledger <#ledger-daml-ledger>`__. These usually `read from the ledger <#reading-from-the-ledger>`_, `send commands <#submitting-commands-writing-to-the-ledger>`__ to the ledger, or both.
 
-There's a lot of information available about application development, starting with the :doc:`/app-dev/index` page.
+There's a lot of information available about application development, starting with the :doc:`/app-dev/app-arch` page.
 
 Ledger API
 ==========

diff --git a/docs/source/daml-integration-kit/index.rst b/docs/source/daml-integration-kit/index.rst
@@ -9,7 +9,7 @@ DAML Integration Kit - ALPHA
 
    /tools/ledger-api-test-tool/index
 
-:doc:`DAML Applications </app-dev/index>` run on DAML Ledgers.
+:doc:`DAML Applications </app-dev/app-arch>` run on DAML Ledgers.
 A DAML Ledger is a server serving the
 :doc:`Ledger API </app-dev/grpc/index>` as per the semantics defined in
 the :doc:`/concepts/ledger-model/index` and the
@@ -120,8 +120,8 @@ To acquire this context, you should:
 
 1. Complete the :doc:`/getting-started/quickstart`.
 2. Get an in-depth understanding of the :doc:`/concepts/ledger-model/index`.
-3. Build a mental model of how the :doc:`Ledger API </app-dev/index>`
-   is used to :doc:`build DAML Applications </app-dev/index>`.
+3. Build a mental model of how the :doc:`Ledger API </app-dev/ledger-api>`
+   is used to :doc:`build DAML Applications </app-dev/app-arch>`.
 
 .. _integration-kit_writing_code:
 
@@ -285,7 +285,7 @@ In the diagram above:
 Explaining this diagram in detail (for brevity, we drop prefixes
 of their qualified names where unambiguous):
 
-:doc:`Ledger API </app-dev/index>`
+:doc:`Ledger API </app-dev/ledger-api>`
   is the collection of gRPC
   services that you would like your `daml-on-<X>-server` to provide.
 ``<X> services``
@@ -367,7 +367,7 @@ Testing a DAML Ledger
 You can test your DAML ledger implementation using :doc:`Ledger API Test Tool
 </tools/ledger-api-test-tool/index>`, which will assess correctness of
 implementation of the :doc:`Ledger API
-</app-dev/index>`. For example, it will show you if
+</app-dev/ledger-api>`. For example, it will show you if
 there are consistency or conformance problem with your implementation.
 
 Assuming that your Ledger API endpoint is accessible at ``localhost:6865``, you can use the tool in the following manner:

diff --git a/docs/source/daml/reference/packages.rst b/docs/source/daml/reference/packages.rst
@@ -15,7 +15,7 @@ DAML archives
 When a DAML project is build with ``daml build``, build artifacts are generated in the hidden
 directory ``.daml/dist/`` relative to the project root directory. The main build artifact of a
 project is the `DAML archive`, recognized by the ``.dar`` file ending. DAML archives are platform
-independent. They can be deployed on a ledger (see :ref:`deploy <deploy-ref_index>`) or can be
+independent. They can be deployed on a ledger (see :ref:`deploy <deploy-ref_overview>`) or can be
 imported into other projects as a package dependency.
 
 Importing DAML archives

diff --git a/docs/source/daml/testing-scenarios.rst b/docs/source/daml/testing-scenarios.rst
@@ -1,6 +1,8 @@
 .. Copyright (c) 2020 The DAML Authors. All rights reserved.
 .. SPDX-License-Identifier: Apache-2.0
 
+.. _testing-using-scenarios:
+
 Testing using scenarios
 #######################
 

diff --git a/docs/source/deploy/generic_ledger.rst b/docs/source/deploy/generic_ledger.rst
@@ -0,0 +1,59 @@
+.. Copyright (c) 2020 The DAML Authors. All rights reserved.
+.. SPDX-License-Identifier: Apache-2.0
+
+.. _deploy-generic-ledger:
+
+Deploying to a generic DAML ledger
+==================================
+
+DAML ledgers expose a unified administration API. This means that deploying to a DAML ledger is no
+different from deploying to your local sandbox.
+
+To deploy to a DAML ledger, run the following command from within your DAML project:
+
+.. code-block:: none
+
+   $ daml deploy --host=<HOST> --port=<PORT> --access-token-file=<TOKEN-FILE>
+
+where ``<HOST>`` and ``<PORT>`` is the hostname and port your ledger is listening on, which defaults
+to port ``6564``. The ``<TOKEN-FILE>`` is needed if your sandbox runs with :ref:`authentication
+<authentication>` and needs to contain a JWT token with an ``admin`` claim. If your sandbox is not
+setup to use any authentication it can be omitted.
+
+Instead of passing ``--host`` and ``--port`` flags to the command above, you can add the following
+section to the project's ``daml.yaml`` file:
+
+.. code-block:: yaml
+
+   ledger:
+       host: <HOSTNAME>
+       port: <PORT>
+
+The ``daml deploy`` command will
+
+#. upload the project's compiled DAR file to the ledger. This will make the DAML templates defined
+   in the current project available to the API users of the sandbox.
+
+#. allocate the parties specified in the project's ``daml.yaml`` on the ledger if they are missing.
+
+For more further interactions with the ledger, use the ``daml ledger`` command. Try running ``daml
+ledger --help`` to get a list of available ledger commands:
+
+.. code-block:: none
+
+   $ daml ledger --help
+   Usage: daml ledger COMMAND
+     Interact with a remote DAML ledger. You can specify the ledger in daml.yaml
+     with the ledger.host and ledger.port options, or you can pass the --host and
+     --port flags to each command below. If the ledger is authenticated, you should
+     pass the name of the file containing the token using the --access-token-file
+     flag.
+
+   Available options:
+     -h,--help                Show this help text
+
+   Available commands:
+     list-parties             List parties known to ledger
+     allocate-parties         Allocate parties on ledger
+     upload-dar               Upload DAR file to ledger
+     navigator                Launch Navigator on ledger