2b23b41391
* add GenMap to the "all types" test generators * report bad GenMap format with DeserializationError, not MatchError * document GenMap JSON * notes on missing features * enable -Xsource:2.13 in transaction * make an Order instance for Value resolvable, but unimplemented * use the skeleton from SValue ordering to make a Value ordering skeleton * add Party Order * add Order instance for SortedLookupList * add Order for FrontStack, deriving everything * factor the Order lookup, and tie a knot in the recursive Value instances * we're going to need this Iterator thing again * replacing Order#contramap with version that supports equalIsNatural * use new equalBy, orderBy for FrontStack, SortedLookupList, ImmArray * _2 comparator, upgrade Name Equal to an Order * incorporate lookup for enums, variants into Value order; record/struct cases * Enum/Variant comparison * looking up the singleton implicitly won't work for non-`object`s, alas * test Order laws for values of all primitive types * test Order laws for record and variant types * test Order laws for enum types * test that enum strings are not compared * use checkLaws for Value Equal as well * test that enums match order to constructor rank * factor genAddend and genAddendNoListMap * reintroduce Order for TypedValueGenerators * more addend order * record, variant order cases * record cons order * deriving Order while decoding from JSON * make ApiCodecCompressed's Cid codec based on the typeclass * test how the Value ordering and the underlying projected value orderings line up - hint: they don't, yet - this is also a template for how we'll check the fidelity with SValue ordering * test how the Value ordering and SValue ordering line up - hint: they don't, yet * typed Arbitrarys have access to Order * produce proper ValueGenMap * inj requires Order, sometimes - we encode this as "all the time" but there is a type-level unification approach to remove this requirement in some cases * make inj a function * test that order doesn't matter for JSON decoder * use Utf8 order for TVG text; don't pretend that base equal works * sort JSON GenMaps, and check for duplicates * make injarb use IntroCtx * remove stray import * Order instances for Bytes, Hash, AbsoluteContractId * require Order[Cid] to decode JSON to LF values * clean up map reordering test * remove unused Instant instance * fake Order instance no longer needed, valid instance defined * test parity of global AbsoluteContractId order and SContractId order * bazel fmt * test AbsoluteContractId Order lawfulness * test duplicate key detection CHANGELOG_BEGIN - [JSON API] Prepare full support for the planned GenMap primitive type. See `issue #5031 <https://github.com/digital-asset/daml/issues/5031>`_. CHANGELOG_END |
||
|---|---|---|
| .. | ||
| configs | ||
| scripts | ||
| source | ||
| theme | ||
| .gitignore | ||
| BUILD.bazel | ||
| error.html | ||
| README.md | ||
| redirect_template.html | ||
| redirects.map | ||
DAML SDK 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
toctreein/docs/source/index.rstand/docs/configs/pdf/index.rst. -
Make sure you preview before you push.
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
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:
--pdfincludes the PDF documentation--genincludes 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 you’re not familiar, it’s 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
docdirective where you can. -
For bullet points (unordered lists), use
-(dashes). -
For code blocks, use the
literalincludedirective if you can: it's best to source code from files that we test whether they compile.
How the docs get built
The docs get built as part of the main daml repo CI, to make sure we don't break any links or do anything else that would cause Sphinx warnings.
Publishing docs
Documentation is published automatically whenever a release is made public on Github. Note that there is a delay so you might have to wait up to an hour until the docs are published after making a release public.
Testing code in docs
TBD