[Self-service error codes] Small fixes for docs/scripts/live-preview.…

…sh (#11856) CHANGELOG_BEGIN CHANGELOG_END
digital-asset · Nov 24, 2021 · 066da4f · 066da4f
1 parent 258fb65
commit 066da4f
Show file tree

Hide file tree

Showing 5 changed files with 21 additions and 12 deletions.
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -1,4 +1,5 @@
 .vscode/settings.json
 /source/app-dev/grpc/proto-docs.rst
+/source/app-dev/grpc/error-codes-inventory.rst
 __pycache__/
 /build/
diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel
@@ -106,7 +106,7 @@ genrule(
         cp -rL docs/source source
 
         mkdir -p -- source/error-codes/self-service
-        cp -- $(location //docs:generate-docs-error-code-inventory-into-rst-file) source/app-dev/grpc/error_codes_inventory.rst
+        cp -L -- $(location //docs:generate-docs-error-code-inventory-into-rst-file) source/app-dev/grpc/error-codes-inventory.rst
         # Copy in Stdlib
         mkdir -p source/daml/stdlib
         tar xf $(location //compiler/damlc:daml-base-rst.tar.gz) \\
@@ -667,8 +667,8 @@ genrule(
 genrule(
     name = "generate-docs-error-code-inventory-into-rst-file",
     srcs = [],
-    outs = ["error_codes_inventory.rst"],
-    cmd = "$(location //ledger/error/generator:generate-docs-error-code-inventory-app) $(location error_codes_inventory.rst)",
+    outs = ["error-codes-inventory.rst"],
+    cmd = "$(location //ledger/error/generator:generate-docs-error-code-inventory-app) $(location error-codes-inventory.rst)",
     tools = ["//ledger/error/generator:generate-docs-error-code-inventory-app"],
     visibility = ["//visibility:public"],
 )

diff --git a/docs/README.md b/docs/README.md
@@ -19,9 +19,10 @@ To edit 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
+- the ledger API proto docs,
+- the Daml standard library reference,
+- the Java bindings reference,
+- error codes inventory.
 
 To edit those docs, edit the content inside the code source.
 
@@ -31,10 +32,11 @@ 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
+- `--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.
+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
 

diff --git a/docs/scripts/live-preview.sh b/docs/scripts/live-preview.sh
@@ -21,6 +21,7 @@ cleanup()
   rm -rf ../source/getting-started/code
   rm -rf ../source/daml/stdlib
   rm -f ../source/app-dev/grpc/proto-docs.rst
+  rm -f ../source/app-dev/grpc/error-codes-inventory.rst
   rm -f ../source/LICENSE
   rm -f ../source/NOTICES
   echo "Done cleanup ... quitting."
@@ -61,8 +62,12 @@ do
     fi
     if [ "$arg" = "--gen" ]; then
 
+        # NOTE:
+        # $BUILD_DIR/source is a symlink into the versioned controlled directory with source .rst files.
+        # When generating files into that directory make sure to remove them before this script ends.
+
         bazel build //docs:generate-docs-error-code-inventory-into-rst-file
-        cp -L ../../bazel-bin/docs/error_codes_inventory.rst $BUILD_DIR/source/app-dev/grpc/error_codes_inventory.rst
+        cp -L ../../bazel-bin/docs/error-codes-inventory.rst $BUILD_DIR/source/app-dev/grpc/error-codes-inventory.rst
 
         # Hoogle
         bazel build //compiler/damlc:daml-base-hoogle.txt
@@ -80,6 +85,7 @@ do
 
         #StdLib
         bazel build //compiler/damlc:daml-base-rst.tar.gz
+        mkdir -p ../source/daml/stdlib
         tar xf ../../bazel-bin/compiler/damlc/daml-base-rst.tar.gz \
             --strip-components 1 -C ../source/daml/stdlib
     fi
@@ -89,4 +95,4 @@ DATE=$(date +"%Y-%m-%d")
 echo { \"$DATE\" : \"$DATE\" } >  $BUILD_DIR/gen/versions.json
 
 pipenv install
-pipenv run sphinx-autobuild -D error_codes_json_export=../../bazel-bin/docs/error_codes_export.json -c $BUILD_DIR/configs/html $BUILD_DIR/source $BUILD_DIR/gen
+pipenv run sphinx-autobuild -c $BUILD_DIR/configs/html $BUILD_DIR/source $BUILD_DIR/gen
diff --git a/docs/source/app-dev/grpc/error-codes.rst b/docs/source/app-dev/grpc/error-codes.rst
@@ -355,7 +355,7 @@ Error Codes Inventory
 
 
 .. This file is generated:
-.. include:: error_codes_inventory.rst
+.. include:: error-codes-inventory.rst
 
 
 Error Codes Migration Guide