daml/docs
Moisés Ackerman 6ef040743f
Support interface choices in daml ledger export (#15189)
* Rename test //daml-script/export/integration-tests/golden:{export-=>}values

* Switch 'daml_ledger_export_test' to use 'run' instead of 'run-legacy-cli-config'

* Extract 'encodeImports' from 'encodeModuleHeader'

* Sort import list in 'daml ledger export'

* Add 'dev' argument to 'daml_ledger_export_test'

* Add interfaceId to ExercisedSelector

* Extract 'encodeExercisedEvent' from 'encodeCmd'

* Split 'encodeCid' into 'encodeCid{Expr,Pat}'

* 'CreatedContract' field 'tplId' now has type 'TemplateId'

* Specialize CreatedContract{=>WithPath}

* 'treeEventCreatedConsumedCids' returns Seq[SimpleCreatedContract] instead of Set[ContractId]

* Change type of 'SimpleCommand' field 'contractId' to 'SimpleCreatedContract'

* Coerce ContractIds to underlying template type

* Use interface ContractId in encodeExercisedEvent if present

* Add test //daml-script/export/integration-tests/golden:interface-choices

* Fix encoding of getAnyChoiceTemplateTypeRep in daml-script converter

* Set getAnyChoiceTemplateTypeRep to interfaceId if available

* fromExercised uses choice instead of templateId to find subtree

fromExercised uses exercised.argument.templateTypeRep instead of exercised.contractId.templateId

Previously it used exercised.contractId.templateId, but now it uses
exercised.argument.getAnyChoiceTemplateTypeRep, which corresponds
to the TemplateTypeRep of the {template,interface} that defined the choice.

* TestData.Exercised now takes a more flexible TestData.Choice argument

* Add unit tests for encoding of exercise of interface choice

* Apply code review suggestions

* sealed {trait=>abstract class} CreatedContract

* Use List instead of Seq

* Use ::= instead of :+= and ++=

changelog_begin
- [Daml export] Added support for interface choices (#15189)
- [Daml export] Export.daml imports are now sorted alphabetically
changelog_end

Co-authored-by: Stephen Compall <stephen.compall@daml.com>
2022-10-19 10:43:04 +02:00
..
configs docs: no index (#14985) 2022-09-15 12:12:12 +02:00
resources/generated-error-pages Improve wording of the conveyance message in error codes docs (#15043) 2022-09-28 08:55:12 +00:00
scripts fix live-preview (#15061) 2022-09-22 10:03:11 +00:00
source Support interface choices in daml ledger export (#15189) 2022-10-19 10:43:04 +02:00
src/test/suite/scala/daml/docs [Error codes doc] Put generated source files of error inventories under version control [DPP-606][DPP-777] (#13181) 2022-03-10 12:06:58 +01:00
theme Make emphasis visible (#14604) 2022-08-04 10:09:23 +02:00
.gitignore [DPP-762][Self-service error codes] Automate generation of inventory of error categories. #11879 2021-11-26 10:22:14 +01:00
BUILD.bazel review daml-intro-10 (#15268) 2022-10-18 17:10:50 +02:00
canton-refs.rst document how to enable dev on both Daml and Canton (#14838) 2022-08-29 11:01:50 +02:00
daml-intro-7.yaml Switch docs for upgrade automation to Canton Sandbox (#12908) 2022-02-14 14:08:32 +00:00
error.html update copyright headers (#12240) 2022-01-03 16:36:51 +00:00
README.md Document docs HEAD build (#13121) 2022-03-02 10:32:00 +01:00
redirect_template.html update copyright headers (#12240) 2022-01-03 16:36:51 +00:00
redirects.map Update redirects.map (#14110) 2022-06-08 09:21:33 -04:00

Daml Documentation

This directory contains all of the documentation that gets published to docs.daml.com.

Writing documentation

The docs are written in reStructuredText, built using Sphinx.

To edit documentation:

  • Same as code: find the file, edit it on a branch, make a PR.

  • For new files, best to copy existing ones, to get the formatting right.

    Don't forget you need to add your file to the toctree in /docs/source/index.rst and /docs/configs/pdf/index.rst.

  • Make sure you preview before you push.

  • Don't insert line-breaks inside inline literals. Building preview will treat this as an error.

Generated documentation

Not all of our docs are in rst files: some get generated. They are:

  • the ledger API proto docs,
  • the Daml standard library reference,
  • the Java bindings reference,
  • error codes inventory.

To edit those docs, edit the content inside the code source.

Previewing

To preview the full docs, as deployed to docs.daml.com, run scripts/preview.sh.

To live-preview the docs, run scripts/live-preview.sh. The script accepts two flags:

  • --pdf includes the PDF documentation,
  • --gen includes the generated documentation.

Note that neither PDF, nor generated docs will benefit from live updates. To update generated docs or PDF docs, quit the preview script with CTRL+C and start it again.

Style conventions

For terminology and other style questions, follow the main DA documentation style guide.

A few pieces of RST guidance:

If youre not familiar, its really worth reading the primer for the basic syntax (emphasis, code text, lists, tables, images, comments, etc).

  • Keep paragraphs all on the same line (no newlines/line breaks).

  • Heading underlines in this hierarchical order:

    ######
    ******
    ======
    ------
    ^^^^^^
    """"""
    
  • For internal links, use the doc directive where you can.

  • For bullet points (unordered lists), use - (dashes).

  • For code blocks, use the literalinclude directive if you can: it's best to source code from files that we test whether they compile.

Updating the table of contents

The table of contents is generated automatically based on the titles and :toctree: entries in the Rst files. However, the root index files docs/source/index.rst and docs/configs/pdf/index.rst are special in two ways:

First, there are different versions for the HTML and the PDF docs build. These should be kept in sync with the difference beeing that in the HTML guide we hide we use captions on :toctree: entries and mark them as :hidden: because the ToC shows up in the sidebar while in the PDF version we use section headers instead of captions and do not hide the :toctree: entries.

The second the index.rst files in the Daml repository are only used for preview in the Daml repository and have no effect on the the published documentation. Instead, we replace them by the index_html.rst and index_pdf.rst files in the assembly repo which combine the documentation from the Daml and the Canton repository. So if you change the root index files in the Daml repository make sure that you apply the same change in the assembly repository.

How the docs get built

The final documentation gets built as part of the assembly repository but the daml repository builds the Daml part of the documentation and checks that the sphinx builds passes without warnings.

Publishing docs

Documentation is published automatically whenever a release is made under https://docs.daml.com/$version/. The documentation at https://docs.daml.com is updated by an hourly cron job to the latest version that has been marked as a non-prerelease on Github.

Testing code in docs

TBD

Building the assembly repo against HEAD

Especially for changes to the table of contents, it can often be useful to see the final version of the docs that is built by the assembly repo based on the current HEAD of the daml repository. For that, you can build and copy the artifacts from the Daml repository to the download directory of the assembly repository as follows:

./docs/scripts/copy-assembly path/to/assembly/docs/download

Afterwards, you can use the usual commands from the assembly repository to build documentation where you use 0.0.0 as the SDK version, e.g.,

./live-preview.sh 0.0.0 2.0.0-rc9