0f5d93e0c3
* Initial commit with create-daml-app master * Include create-daml-app in build rule * Make daml.yaml a template in version and project name * Remove git attributes * Remove license and azure config * Remove scripts * Don't overwrite config files in build rule * Template version numbers in package.json, to be replaced by the assistant * Rename to package.json.template changelog_begin changelog_end * Add copyright headers * Do template substitutions in all .template files And don't special case daml new create-daml-app (so it treats it as a regular template). * Add create-daml-app to integration tests * Remove WIP warning * Move towards setup that works on head * Make local copies of the TS libs in the templates tarball * Hardcode project name for now * Use isExtensionOf * Remove service worker * remove robots.txt (don't even know what it is) * Revert "Make local copies of the TS libs in the templates tarball" This reverts commit 1289581fb4a82af3ab534baf978a2c6ed895d538. * Retemplatize TS lib versions. For head builds these will be installed using npm * Remove daml/ledger from resolutions for daml-ts * Comment about test secret * Remove special create-daml-app assistant command and test that won't work anymore * Remove redundant imports and export * Remove old create-daml-app tests * Remove yarn.lock * Clean up integration test (just daml new and build atm) * Add daml/ledger as a resolution for daml-ts * Remove top level package.json * Update daml.js version * Use new import scheme for generated TS * Update readme with new codegen and build steps * Use start-navigator in daml.yaml * Increase a couple of timeouts in tests (either sandbox or TS lib is a bit slower?) * Update GSG intro with new build steps * Remove daml2ts -p flag and --start-navigator flag from GSG instructions * Don't use start-navigator flag in ui tests * Temporary readme describing how to manually test the create-daml-app template * Update code samples in app arch section of GSG * Update code samples in testing doc * Remove copied create-daml-app code * Indent docs markers to be more subtle * Update visible code in Messages (after) section This needs to be kept up to date properly somehow. * Update text to useLedger * Restore code/ui-before copies until the Bazel magic is figured out We need to make the template code a dependency in the Bazel rule as otherwise we can't find the files in the docs build. * Update create-daml-app/readme and make templates/readme more detailed * Use jsx comments for docs markers so they don't show up in the app |
||
|---|---|---|
| .. | ||
| 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