0cb3541666
* capture the pattern of an optional stream input prefix * allow LiveBegins to be appended - should have been included with #4593 * StreamQuery will parse JsValues instead of Strings * shortcut in HttpServiceTestFixture; clean up InsertDeleteStepTest * compatibly add withOptPrefix stage to WS input * parsing the offset argument * add offset parsing to input stream, but drop it on the floor * another form of the two cases * percolate the starting offset to the next step * percolate the starting offset to the next step * percolate the starting offset to the next step * use transactionsFollowingBoundary in ContractsService if begin offset specified * integration test for scan from offset in WS query * tool for catching the first offset in a stream * documentation * add changelog entry CHANGELOG_BEGIN - [JSON API - Experimental] WebSocket endpoints now support an optional offset argument. See `issue #4509 <https://github.com/digital-asset/daml/issues/4509>`_. CHANGELOG_END * move offset argument doc to later - suggested by @hurryabit; thanks * remove stray TODO - pointed out by @leo-da; thanks * redesign withOptPrefix to make the usage a little easier to follow - suggested by @leo-da; thanks |
||
---|---|---|
.. | ||
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
toctree
in/docs/source/index.rst
and/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:
--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 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
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.
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