d6e5862645
* Add `platform-version` field to `daml.yaml` This PR adds the `platform-version` field to `daml.yaml`. Based on the approach agreed upon in #6558, the logic for this all sits in `daml-helper` and there are no changes to the assistant. The details of how the logic work are in a comment so I’m not going to repeat them here but the commands that are affected are: - `daml sandbox` - `daml sandbox-classic` - `daml json-api` - `daml start` (but only for sandbox and the JSON API, not for Navigator or anything else) For tests, I’ve added a test to the compat workspace that installs two SDKs simultaneously and tries out various combinations and verifies that we get the correct version. Open to other ideas for testing this but that seemed like the most sensible option that actually tests what we run. changelog_begin - [DAML Assistant] You can now specify the version of Sandbox and the JSON API independently of your SDK version by setting ``platform-version`` in your ``daml.yaml``. This is useful if you are deploying to a ledger that is running components from a different SDK version. See https://docs.daml.com/tools/assistant.html#project-config-file-daml-yaml for details. changelog_end * Run platform-version tests changelog_begin changelog_end * Fix tag globbing changelog_begin changelog_end * fmt changelog_begin changelog_end * . changelog_begin changelog_end * Try to fix env vars changelog_begin changelog_end * Remove hardcoded references to 1.2.0 changelog_begin changelog_end * Rephrase doc comment changelog_begin changelog_end * get things to compile changelog_begin changelog_end * maybe fix things for realz changelog_begin changelog_end * Remove debugging output changelog_begin changelog_end * Get angry at windows changelog_begin changelog_end * why is windows changelog_begin changelog_end * . changelog_begin 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