clean-up docs & fix BlackDuck (hopefully) (digital-asset#17975)

kgeonw · Dec 5, 2023 · c6e439b · c6e439b
1 parent 1794212
commit c6e439b
Show file tree

Hide file tree

Showing 13 changed files with 29 additions and 751 deletions.
diff --git a/Pipfile b/Pipfile
@@ -10,4 +10,4 @@ verify_ssl = true
 [packages]
 
 [requires]
-python_version = "3.7"
+python_version = "3.8"
diff --git a/Pipfile.lock b/Pipfile.lock
diff --git a/dev-env/bin/dade-pipenv-lock b/dev-env/bin/dade-pipenv-lock
diff --git a/dev-env/bin/runpipenv b/dev-env/bin/runpipenv
diff --git a/docs/README.md b/docs/README.md
@@ -1,127 +1,18 @@
 # Daml Documentation
 
-This directory contains all of the documentation that gets published to docs.daml.com.
+This directory creates the bundle for [digital-asset/docs.daml.com].
 
-## Writing documentation
-
-The docs are written in [reStructuredText](http://docutils.sourceforge.net/rst.html), built using [Sphinx](http://www.sphinx-doc.org/en/master/).
+[digital-asset/docs.daml.com]: https://github.com/digital-asset/docs.daml.com
 
-To edit documentation:
+## Writing 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. 
-- If you need to change the table of contents, look at the section about it further down
-- **Make sure you preview** before you push. Maybe include screenshots in a comment for your PR if relevant.
-- Don't insert line-breaks inside inline literals. Building preview will treat this as an error.
+Go to [digital-asset/docs.daml.com] and follow the intructions there.
 
 ### 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,
-- error codes inventory.
+- Ledger API proto docs
+- Daml standard library reference
+- Java bindings reference
+- error codes inventory
 
 To edit those docs, edit the content inside the code source.
-
-### Previewing
-
-To preview the docs 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.
-
-The preview is indicative of contents documented in this repository. For the final result, you
-should go to https://github.com/digital-asset/docs.daml.com and consult the preview instructions.
-
-### Style conventions
-
-For terminology and other style questions, follow the [main DA documentation style guide](https://docs.google.com/document/d/1dwE45gyxWXqlr4VTq9mJVnmSyBQ8V30ItucWBbCbViQ/edit).
-
-A few pieces of RST guidance:
-
-If you’re not familiar, it’s really worth reading the [primer](http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) 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. 
-- Before any lists in an .rst file, be sure to add an extra blank line. There should be two carriage returns between the text that comes before a list and the list itself. Otherwise, the list items will all be merged into a single paragraph.
-- 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.
-
-## Updating the table of contents
-
-The table of contents is handled in https://github.com/digital-asset/docs.daml.com.
-
-If you want need to add an item that needs to end up on the table of contents, you need to:
-
-1. get the PR that introduces the new item
-2. wait for the following daily snapshot
-3. follow the instructions on https://github.com/digital-asset/docs.daml.com, in particular with regards to
-   [making changes to the next unreleased version](https://github.com/digital-asset/docs.daml.com#making-changes-to-the-next-unreleased-version)
-
-## Linking to pages from the Canton documentation
-
-This repository only includes content for the Daml SDK. However the Daml documentation includes both
-content from this repository and from [Canton's](https://github.com/digital-asset/canton). This means that
-linking to a page in the Canton documentation requires some additional care. In particular, you have to:
-
-1. find the anchor point to which you want to link in the Canton documentation
-2. add the anchor point name in the `//docs/canton-refs.rst` document (unless it's already there)
-3. refer to the anchor point in your page
-
-You can see a small example of this procedure in
-[this commit](https://github.com/digital-asset/daml/commit/30acaaea777b92712fe46c2062361f5f44b260ce).
-
-## How the docs get built
-
-The final documentation gets built as part of the `assembly`
-repository but the `daml` repository builds the Daml part of the
-documentation and checks that the sphinx builds passes without
-warnings.
-
-## Publishing docs
-
-Documentation is published automatically whenever a release is made
-under `https://docs.daml.com/$version/`.  The documentation at
-`https://docs.daml.com` is updated by an hourly cron job to the latest
-version that has been marked as a non-prerelease on Github.
-
-## Testing code in docs
-
-TBD
-
-## Building the assembly repo against HEAD
-
-Especially for changes to the table of contents, it can often be
-useful to see the final version of the docs that is built by the
-assembly repo based on the current HEAD of the daml repository. For
-that, you can build and copy the artifacts from the Daml repository to
-the `download` directory of the assembly repository as follows:
-
-
-```
-./docs/scripts/copy-assembly path/to/assembly/docs/download
-```
-
-Afterwards, you can use the usual commands from the [assembly
-repository](https://github.com/DACH-NY/assembly/blob/main/docs/README.md)
-to build documentation where you use `0.0.0` as the SDK version, e.g.,
-
-```
-./live-preview.sh 0.0.0 2.0.0-rc9
-```
diff --git a/docs/scripts/Pipfile b/docs/scripts/Pipfile