digital-asset/daml
1
1
Fork 0
mirror of https://github.com/digital-asset/daml.git synced 2024-09-20 09:17:43 +03:00
Code Issues Projects Releases Wiki Activity
e922e1d2fe
daml/docs
History
Moritz Kiefer 7c031f25f7
Upgrade rules_nodejs to version 1.6.0 (#5539) 
* Upgrade rules_nodejs to version 1.6.0

closes #5367

This includes the fixes for the issues in jest that we’ve been seeing.

changelog_begin
changelog_end

* Fix eslint rules

* A bit of progress

* Try to add LinkablePackageInfo (doesn’t seem to work yet)

* Add rootDirs

* revert da_ts_library

* da_ts_library: add LinkablePackageInfo info

* Remove react hook workaround

Since rules_nodejs 1.6.0 this fails with the following error:
```
  ● Test suite failed to run

    Configuration error:

    Could not locate module react mapped as:
    /.../execroot/com_github_digital_asset_daml/bazel-out/k8-opt/bin/language-support/ts/daml-react/test.sh.runfiles/com_github_digital_asset_daml/node_modules/react/umd/react.development.js.

    Please check your configuration for these entries:
    {
      "moduleNameMapper": {
        "/^react$/": "/.../execroot/com_github_digital_asset_daml/bazel-out/k8-opt/bin/language-support/ts/daml-react/test.sh.runfiles/com_github_digital_asset_daml/node_modules/react/umd/react.development.js"
      },
      "resolver": null
    }

      49 | // like a promis without being one.
      50 | /* eslint-disable @typescript-eslint/no-floating-promises */
    > 51 | var react_1 = __importStar(require("react"));
         |                            ^
      52 | var react_hooks_1 = require("@testing-library/react-hooks");
      53 | var index_1 = __importStar(require("./index"));
      54 | var events_1 = require("events");

      at createNoMappedModuleFoundError (../../../../../../../../../../../node_modules/jest-resolve/build/index.js:501:17)
      at Object.<anonymous> (index.test.js:51:28)

Test Suites: 1 failed, 1 total
Tests:       0 total
Snapshots:   0 total
Time:        1.88s
Ran all test suites within paths "language-support/ts/daml-react/DamlLedger.d.ts", "language-support/ts/daml-react/DamlLedger.js", "language-support/ts/daml-react/context.d.ts", "language-support/ts/daml-react/context.js", "language-support/ts/daml-react/hooks.d.ts", "language-support/ts/daml-react/hooks.js", "language-support/ts/daml-react/index.d.ts", "language-support/ts/daml-react/index.js", "language-support/ts/daml-react/index.test.d.ts", "language-support/ts/daml-react/index.test.js".
=
```

* rootDirs is not needed for tsc

This is only required for ts_project

* Update yarn Bazel packages

* docs/theme add missing dependencies

* Remove unused attribute module_root

Co-authored-by: Andreas Herrmann <andreas.herrmann@tweag.io>
2020-04-17 12:03:33 +00:00
..
configs Freeze JSON API v1 (#5387) 2020-04-03 13:58:17 -04:00
scripts Fix redirects, java-bindings javadoc, and live-preview.sh (#5446) 2020-04-07 09:53:26 +02:00
source Add an --output-file option to DAML Script (#5590) 2020-04-17 09:41:02 +02:00
theme Added screenshots to the GSG (#5233) 2020-03-31 15:05:09 +02:00
.gitignore Full documentation for the new assistant (#740) 2019-05-13 16:33:59 +00:00
BUILD.bazel Upgrade rules_nodejs to version 1.6.0 (#5539) 2020-04-17 12:03:33 +00:00
error.html replace DAML Authors with DA in copyright headers (#5228) 2020-03-27 01:26:10 +01:00
README.md JSON API documentation update (#4173) 2020-01-23 14:54:12 -05:00
redirect_template.html replace DAML Authors with DA in copyright headers (#5228) 2020-03-27 01:26:10 +01:00
redirects.map Fix redirects (#5601) 2020-04-17 13:44:16 +02:00

README.md

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