unify heading markup according to README.md (#11919)

CHANGELOG_BEGIN
CHANGELOG_END

docs/source/app-dev/app-arch.rst

@@ -30,7 +30,7 @@ architecture, providing you with an excellent starting point for your own applic
 - deploying your application in the cloud as a Docker container
 
 Backend
-~~~~~~~
+*******
 The backend for your application can be any Daml ledger implementation running your DAR
 (:ref:`Daml Archive <dar-file-dalf-file>`) file.
 
@@ -53,7 +53,7 @@ your frontend and Daml artifacts of your project to a production Daml network. S
 :ref:`Deploying to Daml Ledgers <deploy-ref_overview>` for an in depth manual for specific ledgers.
 
 Frontend
-~~~~~~~~
+********
 
 We recommended building your frontend with the `React <https://reactjs.org>`_ framework. However,
 you can choose virtually any language for your frontend and interact with the ledger via
@@ -93,7 +93,7 @@ If you choose a different JavaScript based frontend framework, the packages ``@d
 connect and issue commands against your ledger.
 
 Authorization
-~~~~~~~~~~~~~
+*************
 
 When you deploy your application to a production ledger, you need to authenticate the identities of
 your users.
@@ -106,7 +106,7 @@ with a Daml ledger that validates authorization of incoming requests. Simply ini
 form of the required tokens is described in the :ref:`Authorization <authorization>` section.
 
 Developer workflow
-~~~~~~~~~~~~~~~~~~
+******************
 
 The SDK enables a local development environment with fast iteration cycles:
 
@@ -129,7 +129,7 @@ See :doc:`Your First Feature </getting-started/first-feature>` for a more detail
 .. _command-deduplication:
 
 Command deduplication
-*********************
+=====================
 
 The interaction of a Daml application with the ledger is inherently asynchronous: applications send commands to the ledger, and some time later they see the effect of that command on the ledger.
 
@@ -158,12 +158,12 @@ For more details on command deduplication, see the :ref:`Ledger API Services <co
 .. _dealing-with-failures:
 
 Dealing with failures
-*********************
+=====================
 
 .. _crash-recovery:
 
 Crash recovery
-==============
+--------------
 
 In order to restart your application from a previously known ledger state,
 your application must keep track of the last ledger offset received
@@ -176,7 +176,7 @@ atomic operation, your application can resume from where it left off.
 .. _failing-over-between-ledger-api-endpoints:
 
 Failing over between Ledger API endpoints
-=========================================
+-----------------------------------------
 
 Some Daml Ledgers support exposing multiple eventually consistent Ledger API
 endpoints where command deduplication works across these Ledger API endpoints.
@@ -210,7 +210,7 @@ new endpoint, it will resume normal operation.
 .. _dealing-with-time:
 
 Dealing with time
-*****************
+=================
 
 The Daml language contains a function :ref:`getTime <daml-ref-gettime>` which returns a rough estimate of “current time” called *Ledger Time*. The notion of time comes with a lot of problems in a distributed setting: different participants might run different clocks, there may be latencies due to calculation and network, clocks may drift against each other over time, etc.
 

docs/source/app-dev/bindings-java/example.rst

@@ -26,7 +26,7 @@ To set up the example projects, clone the public GitHub repository at `github.co
 This project contains three examples of the PingPong application, built with gRPC (non-reactive), Reactive and Reactive Component bindings respectively.
 
 Example project
-********************************************************
+***************
 
 PingPongMain.java
 =================

docs/source/app-dev/bindings-ts/daml2js.rst

@@ -11,7 +11,7 @@ Inputs to the command are DAR files. Outputs are JavaScript packages with TypeSc
 The generated packages use the library `@daml/types <https://github.com/digital-asset/daml/tree/main/language-support/ts/daml-types>`_.
 
 Usage
------
+*****
 
 In outline, the command to generate JavaScript and TypeScript typings from Daml is ``daml codegen js -o OUTDIR DAR`` where ``DAR`` is the path to a DAR file (generated via ``daml build``) and ``OUTDIR`` is a directory where you want the artifacts to be written.
 
@@ -37,7 +37,7 @@ Here's a complete example on a project built from the standard "skeleton" templa
 To get a quickstart idea of how to use what has been generated, you may wish to jump to the `Templates and choices`_ section and return to the reference material that follows as needed.
 
 Primitive Daml types: @daml/types
----------------------------------
+*********************************
 
 To understand the TypeScript typings produced by the code generator, it is helpful to keep in mind this quick review of the TypeScript equivalents of the primitive Daml types provided by @daml/types.
 
@@ -94,12 +94,12 @@ To understand the TypeScript typings produced by the code generator, it is helpf
    The TypeScript definition of type ``Optional<τ>`` in the above table might look complicated. It accounts for differences in the encoding of optional values when nested versus when they are not (i.e. "top-level"). For example, ``null`` and ``"foo"`` are two possible values of ``Optional<Text>`` whereas, ``[]`` and ``["foo"]`` are two possible values of type ``Optional<Optional<Text>>`` (``null`` is another possible value, ``[null]`` is **not**).
 
 Daml to TypeScript mappings
----------------------------
+***************************
 
 The mappings from Daml to TypeScript are best explained by example.
 
 Records
-~~~~~~~
+=======
 
 In Daml, we might model a person like this.
 
@@ -124,7 +124,7 @@ Given the above definition, the generated TypeScript code will be as follows.
    }
 
 Variants
-~~~~~~~~
+========
 
 This is a Daml type for a language of additive expressions.
 
@@ -147,7 +147,7 @@ In TypeScript, it is represented as a `discriminated union <https://www.typescri
      |  { tag: 'Add'; value: {_1: Expr<a>, _2: Expr<a>} }
 
 Sum-of-products
-~~~~~~~~~~~~~~~~
+===============
 
 Let's slightly modify the ``Expr a`` type of the last section into the following.
 
@@ -179,7 +179,7 @@ Compared to the earlier definition, the ``Add`` case is now in terms of a record
 The thing to note is how the definition of the ``Add`` case has given rise to a record type definition ``Expr.Add``.
 
 Enums
-~~~~~
+=====
 
 Given a Daml enumeration like this,
 
@@ -203,7 +203,7 @@ the generated TypeScript will consist of a type declaration and the definition o
    } as const;
 
 Templates and choices
-~~~~~~~~~~~~~~~~~~~~~
+=====================
 
 Here is a Daml template of a basic 'IOU' contract.
 

docs/source/concepts/ledger-model/index.rst

@@ -4,7 +4,7 @@
 .. _da-ledgers:
 
 Daml Ledger Model
-=================
+#################
 
 Daml Ledgers enable multi-party workflows by providing
 parties with a virtual *shared ledger*, which encodes the current

docs/source/concepts/ledger-model/ledger-daml.rst

@@ -4,7 +4,7 @@
 .. _da-model-daml:
 
 Daml: Defining Contract Models Compactly
-----------------------------------------
+########################################
 
 As described in preceding sections, both the integrity and privacy notions depend on
 a contract model, and such a model must specify:

docs/source/concepts/ledger-model/ledger-exceptions.rst

@@ -4,7 +4,7 @@
 .. _da-model-exceptions:
 
 Exceptions
-----------
+##########
 
 The introduction of exceptions, a new Daml feature, has many implications
 for the ledger model. This page describes the changes to the ledger model
@@ -15,7 +15,7 @@ introduced as part of this new feature.
    incorporated into the rest of the ledger model.
 
 Structure
-+++++++++
+*********
 
 Under the new feature, Daml programs can raise and catch exceptions.
 When an exception is caught in a `catch` block, the subtransaction
@@ -71,7 +71,7 @@ moment, for some reason, and a "cancel" exercise has been issued in response.
    :width: 80%
 
 Consistency
-+++++++++++
+***********
 
 In the previous section on :ref:`consistency <da-model-consistency>`,
 we defined a "before-after" relation on ledger actions. This notion needs
@@ -123,7 +123,7 @@ And the third:
 As you can see, in each of these continuities, no contract was consumed twice.
 
 Transaction Normalization
-+++++++++++++++++++++++++
+*************************
 
 The same "before-after" relation can be represented in more than one way using
 rollback nodes. For example, the following three transactions have the same
@@ -205,7 +205,7 @@ contain normalized transactions. This also applies to projected transactions.
 An unnormalized transaction is always invalid.
 
 Authorization
-+++++++++++++
+*************
 
 Since they are not ledger actions, rollback nodes do not have authorizers
 directly. Instead, a ledger is well-authorized exactly when the same ledger
@@ -232,7 +232,7 @@ This is captured in the following rules:
   the required authorizers of its children.
 
 Privacy
-+++++++
+*******
 
 Rollback nodes also have an interesting effect on the notion of privacy in
 the ledger model. When projecting a transaction for a party `p`, it's
@@ -279,7 +279,7 @@ closed under projections for any party 'p'. This is a weaker requirement
 that matches what we actually need.
 
 Relation to Daml Exceptions
-+++++++++++++++++++++++++++
+***************************
 
 Rollback nodes are created when an exception is thrown and caught within
 the same transaction. In particular, any exception that is caught within

docs/source/concepts/ledger-model/ledger-integrity.rst

@@ -4,15 +4,15 @@
 .. _da-model-integrity:
 
 Integrity
----------
+#########
 
 This section addresses the question of who can request which
 changes.
 
 .. _da-model-validity:
 
 Valid Ledgers
-+++++++++++++
+*************
 
 At the core is the concept of a *valid ledger*; changes
 are permissible if adding the corresponding commit to the
@@ -37,7 +37,7 @@ parties) requesting the change; the other two are general.
 .. _da-model-consistency:
 
 Consistency
-+++++++++++
+***********
 
 Consistency consists of two parts:
 
@@ -65,7 +65,7 @@ Then, `act'` happens after `act`.
 .. _da-model-contract-consistency:
 
 Contract consistency
-~~~~~~~~~~~~~~~~~~~~
+====================
 
 Contract consistency ensures that contracts are used after they have been created and before they are consumed.
 
@@ -132,7 +132,7 @@ of contracts `Iou Bank P` and `PaintAgree P A`.
 .. _da-model-key-consistency:
 
 Key consistency
-~~~~~~~~~~~~~~~
+===============
 
 Contract keys introduce a key uniqueness constraint for the ledger.
 To capture this notion, the contract model must specify for every contract in the system whether the contract has a key and, if so, the key.
@@ -197,14 +197,14 @@ Key consistency extends to actions, transactions and lists of transactions just
 .. _da-model-ledger-consistency:
 
 Ledger consistency
-~~~~~~~~~~~~~~~~~~
+==================
 
 Definition »ledger consistency«
   A ledger is **consistent** if it is consistent for all contracts and for all keys.
 
 
 Internal consistency
-~~~~~~~~~~~~~~~~~~~~
+====================
 The above consistency requirement is too strong for actions and transactions
 in isolation.
 For example, the acceptance transaction from the paint offer example is not consistent as a ledger, because `PaintOffer A P Bank`
@@ -271,7 +271,7 @@ In the :ref:`blacklisting example <paint-offer-blacklist>`, `P`\ 's transaction
 .. _da-model-conformance:
 
 Conformance
-+++++++++++
+***********
 
 The *conformance* condition constrains the actions that may occur on the
 ledger. This is done by considering a **contract model** `M` (or a **model** for short),
@@ -328,7 +328,7 @@ not contain the top-level action she is trying to commit.
 .. _da-model-authorization:
 
 Authorization
-+++++++++++++
+*************
 
 The last criterion rules out the last two problematic examples,
 :ref:`an obligation imposed on a painter <obligation-imposed-on-painter>`,
@@ -348,7 +348,7 @@ and imposed on the contract's *signatories*.
 .. _da-signatories-agreements-maintainers:
 
 Signatories, Agreements, and Maintainers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+========================================
 
 To capture these elements of real-world contracts, the **contract model**
 additionally specifies, for each contract in the system:
@@ -403,7 +403,7 @@ signatories yields the image below.
 .. _da-ledgers-authorization-rules:
 
 Authorization Rules
-~~~~~~~~~~~~~~~~~~~
+===================
 
 Signatories allow one to precisely state that the painter has an obligation.
 The imposed obligation is intuitively invalid because the painter did not
@@ -446,7 +446,7 @@ We lift this notion to ledgers, whereby a ledger is well-authorized exactly when
 
 
 Examples
-~~~~~~~~
+========
 
 An intuition for how the authorization definitions work is most easily
 developed by looking at some examples. The main example, the
@@ -517,7 +517,7 @@ The rationale for making the maintainers required authorizers for a **NoSuchKey*
 is discussed in the next section about :ref:`privacy <da-model-privacy-authorization>`.
 
 Valid Ledgers, Obligations, Offers and Rights
-+++++++++++++++++++++++++++++++++++++++++++++
+*********************************************
 
 Daml ledgers are designed to mimic real-world interactions between
 parties, which are governed by contract law. The validity conditions