Upgrade sphinx (#12968)

* Upgrade sphinx Don’t want to be stuck on 1.8.3 forever. The current version is 4.4.0 (this upgrades to 4.3.1 which is the latest in nixpkgs). I did had to drop footnotebackref. This runs into the same issue as https://tex.stackexchange.com/questions/137594/hyperref-footnotebackref-in-longtable but just copying the fix doesn’t work and I don’t understand enough about the details here to fix this myself. We have 7 footnotes in the Daml docs + some in the Canton docs. That does not seem worth sticking on a sphinx version from 2018 for just to get backreferences from footnotes to the link on the same page. changelog_begin changelog_end * turns out you need fonts maybe * . changelog_begin changelog_end * suppport :force: in daml-docs changelog_begin changelog_end
2024-09-19 16:57:40 +03:00 · 2022-02-22 15:30:15 +01:00 · 2022-02-22 15:30:15 +01:00 · 8a966bfaf3
commit 8a966bfaf3
parent 92af00c5c1
15 changed files with 160 additions and 101 deletions
--- a/2
+++ b/2
@ -506,7 +506,7 @@ nixpkgs_package(
 #sphinx
 nixpkgs_package(
    name = "sphinx_nix",
-    attribute_path = "sphinx183-exts",
+    attribute_path = "sphinx-exts",
    nix_file = "//nix:bazel.nix",
    nix_file_deps = common_nix_file_deps,
    repositories = dev_env_nix_repos,
--- a/compiler/damlc/daml-doc/src/DA/Daml/Doc/Render/Rst.hs
+++ b/compiler/damlc/daml-doc/src/DA/Daml/Doc/Render/Rst.hs
@ -154,8 +154,13 @@ docTextToRst = T.lines . renderStrict . layoutPretty defaultLayoutOptions . rend
        DOCUMENT -> Pretty.align (Pretty.concatWith (\x y -> x <> Pretty.line <> Pretty.line <> y) (map render ns))

        PARAGRAPH -> Pretty.align (foldMap render ns)
-        CODE_BLOCK _info t ->
-          Pretty.align (Pretty.vsep [".. code-block:: daml", "", Pretty.indent 2 (pretty t)])
+        CODE_BLOCK info t ->
+          -- Force rendering of code that doesn’t pass the highlighter.
+          let force = ["  :force:" | info == "daml-force"]
+          in Pretty.align $ Pretty.vsep $
+               ".. code-block:: daml" :
+               force <>
+               ["", Pretty.indent 2 (pretty t)]
        LIST ListAttributes{..} -> Pretty.align (Pretty.vsep (zipWith (renderListItem listType) [1..] ns))

        EMPH -> Pretty.enclose "*" "*" (foldMap render ns)
--- a/compiler/damlc/daml-stdlib-src/DA/Bifunctor.daml
+++ b/compiler/damlc/daml-stdlib-src/DA/Bifunctor.daml
@ -21,13 +21,13 @@ module DA.Bifunctor(Bifunctor(..)) where
 --
 -- If you supply bimap, you should ensure that:
 --
-- ```
-- bimap identity identity ≡ identity
+-- ```daml-force
+-- `bimap identity identity` ≡ `identity`
 -- ```
 --
 -- If you supply first and second, ensure:
 --
-- ```
+-- ```daml-force
 -- first identity ≡ identity
 -- second identity ≡ identity
 -- 
@ -35,13 +35,13 @@ module DA.Bifunctor(Bifunctor(..)) where
 --
 -- If you supply both, you should also ensure:
 --
-- ```
+-- ```daml-force
 -- bimap f g ≡ first f . second g
 -- ```
 --
 -- By parametricity, these will ensure that:
 --
-- ```
+-- ```daml-force
 -- 
 -- bimap  (f . g) (h . i) ≡ bimap f h . bimap g i
 -- first  (f . g) ≡ first  f . first  g
@ -53,7 +53,7 @@ class Bifunctor p where

    -- | Map over both arguments at the same time.
    --
-    -- ```
+    -- ```daml-force
    -- bimap f g ≡ first f . second g
    -- ```
    --
@ -75,7 +75,7 @@ class Bifunctor p where

    -- | Map covariantly over the first argument.
    --
-    -- ```
+    -- ```daml-force
    -- first f ≡ bimap f identity
    -- ```
    --
@ -94,7 +94,7 @@ class Bifunctor p where

    -- | Map covariantly over the second argument.
    --
-    -- ```
+    -- ```daml-force
    -- second ≡ bimap identity
    -- ```
    --
--- a/compiler/damlc/daml-stdlib-src/DA/Internal/LF.daml
+++ b/compiler/damlc/daml-stdlib-src/DA/Internal/LF.daml
@ -89,7 +89,7 @@ partyToText = primitive @"BEToText"
 -- This function, together with `partyToText`, forms an isomorphism between
 -- valid party strings and parties. In other words, the following equations hold:
 --
-- ```
+-- ```daml-force
 -- ∀ p. partyFromText (partyToText p) = Some p
 -- ∀ txt p. partyFromText txt = Some p ==> partyToText p = txt
 -- ```
--- a/deps.bzl
+++ b/deps.bzl
@ -360,3 +360,17 @@ java_import(
            strip_prefix = "canton-community-1.0.0-SNAPSHOT",
            urls = ["https://www.canton.io/releases/canton-community-20220214.tar.gz"],
        )
+
+    if "freefont" not in native.existing_rules():
+        http_archive(
+            name = "freefont",
+            build_file_content = """
+filegroup(
+  name = "fonts",
+  srcs = glob(["**/*.otf"]),
+  visibility = ["//visibility:public"],
+)""",
+            sha256 = "3a6c51868c71b006c33c4bcde63d90927e6fcca8f51c965b8ad62d021614a860",
+            strip_prefix = "freefont-20120503",
+            urls = ["http://ftp.gnu.org/gnu/freefont/freefont-otf-20120503.tar.gz"],
+        )
--- a/docs/BUILD.bazel
+++ b/docs/BUILD.bazel
@ -246,17 +246,6 @@ EOF

    export LC_ALL=en_US.UTF-8
    export LANG=en_US.UTF-8
-    # Sphinx 1.8.3 triggers the following warning:
-    #
-    #   /nix/store/1v39mhhyn48s251przk2fwcvgm71vfqi-python3.7-sphinx-1.8.3/lib/python3.7/site-packages/sphinx/writers/html.py:462: FutureWarning:
-    #      The iterable returned by Node.traverse()
-    #      will become an iterator instead of a list in Docutils > 0.16.
-    #     target_node = image_nodes and image_nodes[0] or node.parent
-    #
-    # We are using an older Sphinx (1.8.3) with a more recent nixpkgs revision.
-    # Unfortunately, an update is not so easy because Sphinx 2.3.1 breaks
-    # the PDF documentation due to issues with the FreeSerif font in the
-    # fontspec package. So, for now we ignore `FutureWarning`.
    SPHINX_BUILD_EXIT_CODE=0
    # We hide the output unless we get a failure to make the builds less noisy.
    SPHINX_BUILD_OUTPUT=$$($(location @sphinx_nix//:bin/sphinx-build) -W -b {target} -c $$DIR/source/configs/{name} $$DIR/source/source $$DIR/target 2>&1) || SPHINX_BUILD_EXIT_CODE=$$?
@ -335,7 +324,7 @@ genrule(

 filegroup(
    name = "pdf-fonts",
-    srcs = glob(["configs/pdf/fonts/**"]),
+    srcs = glob(["configs/pdf/fonts/**"]) + ["@freefont//:fonts"],
 )

 pkg_tar(
--- a/docs/configs/html/conf.py
+++ b/docs/configs/html/conf.py
@ -181,6 +181,6 @@ rst_prolog = """
 # Import the Daml lexer
 def setup(sphinx):
    from pygments_daml_lexer import DAMLLexer
-    sphinx.add_lexer("daml", DAMLLexer())
+    sphinx.add_lexer("daml", DAMLLexer)
    from typescript import TypeScriptLexer
-    sphinx.add_lexer("tsx", TypeScriptLexer())
+    sphinx.add_lexer("tsx", TypeScriptLexer)
--- a/docs/configs/pdf/conf.py
+++ b/docs/configs/pdf/conf.py
@ -102,7 +102,7 @@ html_theme_options = {
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = []

 # Don't show "powered by sphinx"
 html_show_sphinx = False
@ -156,8 +156,6 @@ latex_elements = {
        \usepackage{eso-pic}
        \usepackage{lipsum}

-        \usepackage{footnotebackref} %%link at the footnote to go to the place of footnote in the text
-
        %% spacing between line
        \usepackage{setspace}
        %%%%\onehalfspacing
@ -340,6 +338,6 @@ rst_prolog = """
 # Import the Daml lexer
 def setup(sphinx):
    from pygments_daml_lexer import DAMLLexer
-    sphinx.add_lexer("daml", DAMLLexer())
+    sphinx.add_lexer("daml", DAMLLexer)
    from typescript import TypeScriptLexer
-    sphinx.add_lexer("tsx", TypeScriptLexer())
+    sphinx.add_lexer("tsx", TypeScriptLexer)
--- a/docs/scripts/Pipfile
+++ b/docs/scripts/Pipfile
@ -8,7 +8,7 @@ verify_ssl = true
 [packages]
 sphinx-autobuild = "*"
 sphinx-copybutton = "==0.2.12"
-sphinx = "==1.8.3"
+sphinx = "==4.3.1"
 jinja2 = ">=2.11.3"
 urllib3 = ">=1.26.5"

--- a/docs/scripts/Pipfile.lock
+++ b/docs/scripts/Pipfile.lock
@ -1,7 +1,7 @@
 {
    "_meta": {
        "hash": {
-            "sha256": "508c84ea1af3ed83ef19092243ff094c7c64fb65e5e20e149e52693a4625c802"
+            "sha256": "d0d50c703774816e027e5d1f9530f1934c1f9890bf64a2310c0059d93313815a"
        },
        "pipfile-spec": 6,
        "requires": {
@ -32,17 +32,18 @@
        },
        "certifi": {
            "hashes": [
-                "sha256:2bbf76fd432960138b3ef6dda3dde0544f27cbf8546c458e60baf371917ba9ee",
-                "sha256:50b1e4f8446b06f41be7dd6338db18e0990601dce795c2b1686458aa7e8fa7d8"
+                "sha256:78884e7c1d4b00ce3cea67b44566851c4343c120abd683433ce934a68ea58872",
+                "sha256:d62a0163eb4c2344ac042ab2bdf75399a71a2d8c7d47eac2e2ee91b9d6339569"
            ],
-            "version": "==2021.5.30"
+            "version": "==2021.10.8"
        },
-        "chardet": {
+        "charset-normalizer": {
            "hashes": [
-                "sha256:0d6f53a15db4120f2b08c94f11e7d93d2c911ee118b6b30a04ec3ee8310179fa",
-                "sha256:f864054d66fd9118f2e67044ac8981a54775ec5b67aed0441892edb553d21da5"
+                "sha256:2857e29ff0d34db842cd7ca3230549d1a697f96ee6d3fb071cfa6c7393832597",
+                "sha256:6881edbebdb17b39b4eaaa821b438bf6eddffb4468cf344f09f89def34a8b1df"
            ],
-            "version": "==4.0.0"
+            "markers": "python_version >= '3'",
+            "version": "==2.0.12"
        },
        "colorama": {
            "hashes": [
@ -60,25 +61,26 @@
        },
        "idna": {
            "hashes": [
-                "sha256:b307872f855b18632ce0c21c5e45be78c0ea7ae4c15c828c20788b26921eb3f6",
-                "sha256:b97d804b1e9b523befed77c48dacec60e6dcb0b5391d57af6a65a312a90648c0"
+                "sha256:84d9dd047ffa80596e0f246e2eab0b391788b0503584e8945f2368256d2735ff",
+                "sha256:9d643ff0a55b762d5cdb124b8eaa99c66322e2157b69160bc32796e824360e6d"
            ],
-            "version": "==2.10"
+            "markers": "python_version >= '3'",
+            "version": "==3.3"
        },
        "imagesize": {
            "hashes": [
-                "sha256:6965f19a6a2039c7d48bca7dba2473069ff854c36ae6f19d2cde309d998228a1",
-                "sha256:b1f6b5a4eab1f73479a50fb79fcf729514a900c341d8503d62a62dbc4127a2b1"
+                "sha256:1db2f82529e53c3e929e8926a1fa9235aa82d0bd0c580359c67ec31b2fddaa8c",
+                "sha256:cd1750d452385ca327479d45b64d9c7729ecf0b3969a58148298c77092261f9d"
            ],
-            "version": "==1.2.0"
+            "version": "==1.3.0"
        },
        "jinja2": {
            "hashes": [
-                "sha256:1f06f2da51e7b56b8f238affdd6b4e2c61e39598a378cc49345bc1bd42a978a4",
-                "sha256:703f484b47a6af502e743c9122595cc812b0271f661722403114f71a79d0f5a4"
+                "sha256:077ce6014f7b40d03b47d1f1ca4b0fc8328a692bd284016f806ed0eaca390ad8",
+                "sha256:611bb273cd68f3b993fabdc4064fc858c5b47a973cb5aa7999ec1ba405c87cd7"
            ],
            "index": "pypi",
-            "version": "==3.0.1"
+            "version": "==3.0.3"
        },
        "livereload": {
            "hashes": [
@ -91,32 +93,67 @@
                "sha256:01a9b8ea66f1658938f65b93a85ebe8bc016e6769611be228d797c9d998dd298",
                "sha256:023cb26ec21ece8dc3907c0e8320058b2e0cb3c55cf9564da612bc325bed5e64",
                "sha256:0446679737af14f45767963a1a9ef7620189912317d095f2d9ffa183a4d25d2b",
+                "sha256:04635854b943835a6ea959e948d19dcd311762c5c0c6e1f0e16ee57022669194",
                "sha256:0717a7390a68be14b8c793ba258e075c6f4ca819f15edfc2a3a027c823718567",
                "sha256:0955295dd5eec6cb6cc2fe1698f4c6d84af2e92de33fbcac4111913cd100a6ff",
+                "sha256:0d4b31cc67ab36e3392bbf3862cfbadac3db12bdd8b02a2731f509ed5b829724",
                "sha256:10f82115e21dc0dfec9ab5c0223652f7197feb168c940f3ef61563fc2d6beb74",
+                "sha256:168cd0a3642de83558a5153c8bd34f175a9a6e7f6dc6384b9655d2697312a646",
                "sha256:1d609f577dc6e1aa17d746f8bd3c31aa4d258f4070d61b2aa5c4166c1539de35",
+                "sha256:1f2ade76b9903f39aa442b4aadd2177decb66525062db244b35d71d0ee8599b6",
+                "sha256:20dca64a3ef2d6e4d5d615a3fd418ad3bde77a47ec8a23d984a12b5b4c74491a",
+                "sha256:2a7d351cbd8cfeb19ca00de495e224dea7e7d919659c2841bbb7f420ad03e2d6",
+                "sha256:2d7d807855b419fc2ed3e631034685db6079889a1f01d5d9dac950f764da3dad",
                "sha256:2ef54abee730b502252bcdf31b10dacb0a416229b72c18b19e24a4509f273d26",
+                "sha256:36bc903cbb393720fad60fc28c10de6acf10dc6cc883f3e24ee4012371399a38",
+                "sha256:37205cac2a79194e3750b0af2a5720d95f786a55ce7df90c3af697bfa100eaac",
                "sha256:3c112550557578c26af18a1ccc9e090bfe03832ae994343cfdacd287db6a6ae7",
+                "sha256:3dd007d54ee88b46be476e293f48c85048603f5f516008bee124ddd891398ed6",
+                "sha256:4296f2b1ce8c86a6aea78613c34bb1a672ea0e3de9c6ba08a960efe0b0a09047",
                "sha256:47ab1e7b91c098ab893b828deafa1203de86d0bc6ab587b160f78fe6c4011f75",
                "sha256:49e3ceeabbfb9d66c3aef5af3a60cc43b85c33df25ce03d0031a608b0a8b2e3f",
+                "sha256:4dc8f9fb58f7364b63fd9f85013b780ef83c11857ae79f2feda41e270468dd9b",
                "sha256:4efca8f86c54b22348a5467704e3fec767b2db12fc39c6d963168ab1d3fc9135",
                "sha256:53edb4da6925ad13c07b6d26c2a852bd81e364f95301c66e930ab2aef5b5ddd8",
+                "sha256:5855f8438a7d1d458206a2466bf82b0f104a3724bf96a1c781ab731e4201731a",
                "sha256:594c67807fb16238b30c44bdf74f36c02cdf22d1c8cda91ef8a0ed8dabf5620a",
+                "sha256:5b6d930f030f8ed98e3e6c98ffa0652bdb82601e7a016ec2ab5d7ff23baa78d1",
+                "sha256:5bb28c636d87e840583ee3adeb78172efc47c8b26127267f54a9c0ec251d41a9",
+                "sha256:60bf42e36abfaf9aff1f50f52644b336d4f0a3fd6d8a60ca0d054ac9f713a864",
                "sha256:611d1ad9a4288cf3e3c16014564df047fe08410e628f89805e475368bd304914",
+                "sha256:6300b8454aa6930a24b9618fbb54b5a68135092bc666f7b06901f897fa5c2fee",
+                "sha256:63f3268ba69ace99cab4e3e3b5840b03340efed0948ab8f78d2fd87ee5442a4f",
                "sha256:6557b31b5e2c9ddf0de32a691f2312a32f77cd7681d8af66c2692efdbef84c18",
                "sha256:693ce3f9e70a6cf7d2fb9e6c9d8b204b6b39897a2c4a1aa65728d5ac97dcc1d8",
                "sha256:6a7fae0dd14cf60ad5ff42baa2e95727c3d81ded453457771d02b7d2b3f9c0c2",
                "sha256:6c4ca60fa24e85fe25b912b01e62cb969d69a23a5d5867682dd3e80b5b02581d",
+                "sha256:6fcf051089389abe060c9cd7caa212c707e58153afa2c649f00346ce6d260f1b",
                "sha256:7d91275b0245b1da4d4cfa07e0faedd5b0812efc15b702576d103293e252af1b",
+                "sha256:89c687013cb1cd489a0f0ac24febe8c7a666e6e221b783e53ac50ebf68e45d86",
+                "sha256:8d206346619592c6200148b01a2142798c989edcb9c896f9ac9722a99d4e77e6",
                "sha256:905fec760bd2fa1388bb5b489ee8ee5f7291d692638ea5f67982d968366bef9f",
                "sha256:97383d78eb34da7e1fa37dd273c20ad4320929af65d156e35a5e2d89566d9dfb",
                "sha256:984d76483eb32f1bcb536dc27e4ad56bba4baa70be32fa87152832cdd9db0833",
+                "sha256:99df47edb6bda1249d3e80fdabb1dab8c08ef3975f69aed437cb69d0a5de1e28",
+                "sha256:9f02365d4e99430a12647f09b6cc8bab61a6564363f313126f775eb4f6ef798e",
                "sha256:a30e67a65b53ea0a5e62fe23682cfe22712e01f453b95233b25502f7c61cb415",
                "sha256:ab3ef638ace319fa26553db0624c4699e31a28bb2a835c5faca8f8acf6a5a902",
+                "sha256:aca6377c0cb8a8253e493c6b451565ac77e98c2951c45f913e0b52facdcff83f",
+                "sha256:add36cb2dbb8b736611303cd3bfcee00afd96471b09cda130da3581cbdc56a6d",
                "sha256:b2f4bf27480f5e5e8ce285a8c8fd176c0b03e93dcc6646477d4630e83440c6a9",
                "sha256:b7f2d075102dc8c794cbde1947378051c4e5180d52d276987b8d28a3bd58c17d",
+                "sha256:baa1a4e8f868845af802979fcdbf0bb11f94f1cb7ced4c4b8a351bb60d108145",
                "sha256:be98f628055368795d818ebf93da628541e10b75b41c559fdf36d104c5787066",
+                "sha256:bf5d821ffabf0ef3533c39c518f3357b171a1651c1ff6827325e4489b0e46c3c",
+                "sha256:c47adbc92fc1bb2b3274c4b3a43ae0e4573d9fbff4f54cd484555edbf030baf1",
+                "sha256:cdfba22ea2f0029c9261a4bd07e830a8da012291fbe44dc794e488b6c9bb353a",
+                "sha256:d6c7ebd4e944c85e2c3421e612a7057a2f48d478d79e61800d81468a8d842207",
                "sha256:d7f9850398e85aba693bb640262d3611788b1f29a79f0c93c565694658f4071f",
+                "sha256:d8446c54dc28c01e5a2dbac5a25f071f6653e6e40f3a8818e8b45d790fe6ef53",
+                "sha256:deb993cacb280823246a026e3b2d81c493c53de6acfd5e6bfe31ab3402bb37dd",
+                "sha256:e0f138900af21926a02425cf736db95be9f4af72ba1bb21453432a07f6082134",
+                "sha256:e9936f0b261d4df76ad22f8fee3ae83b60d7c3e871292cd42f40b81b70afae85",
+                "sha256:f0567c4dc99f264f49fe27da5f735f414c4e7e7dd850cfd8e69f0862d7c74ea9",
                "sha256:f5653a225f31e113b152e56f154ccbe59eeb1c7487b39b9d9f9cdb58e6c79dc5",
                "sha256:f826e31d18b516f653fe296d967d700fddad5901ae07c622bb3705955e1faa94",
                "sha256:f8ba0e8349a38d3001fae7eadded3f6606f0da5d748ee53cc1dab1d6527b9509",
@ -127,38 +164,38 @@
        },
        "packaging": {
            "hashes": [
-                "sha256:5b327ac1320dc863dca72f4514ecc086f31186744b84a230374cc1fd776feae5",
-                "sha256:67714da7f7bc052e064859c05c595155bd1ee9f69f76557e21f051443c20947a"
+                "sha256:dd47c42927d89ab911e606518907cc2d3a1f38bbd026385970643f9c5b8ecfeb",
+                "sha256:ef103e05f519cdc783ae24ea4e2e0f508a9c99b2d4969652eed6a2e1ea5bd522"
            ],
-            "version": "==20.9"
+            "version": "==21.3"
        },
        "pygments": {
            "hashes": [
-                "sha256:a18f47b506a429f6f4b9df81bb02beab9ca21d0a5fee38ed15aef65f0545519f",
-                "sha256:d66e804411278594d764fc69ec36ec13d9ae9147193a1740cd34d272ca383b8e"
+                "sha256:44238f1b60a76d78fc8ca0528ee429702aae011c265fe6a8dd8b63049ae41c65",
+                "sha256:4e426f72023d88d03b2fa258de560726ce890ff3b630f88c21cbb8b2503b8c6a"
            ],
-            "version": "==2.9.0"
+            "version": "==2.11.2"
        },
        "pyparsing": {
            "hashes": [
-                "sha256:c203ec8783bf771a155b207279b9bccb8dea02d8f0c9e5f8ead507bc3246ecc1",
-                "sha256:ef9d7589ef3c200abe66653d3f1ab1033c3c419ae9b9bdb1240a85b024efc88b"
+                "sha256:18ee9022775d270c55187733956460083db60b37d0d0fb357445f3094eed3eea",
+                "sha256:a6c06a88f252e6c322f65faf8f418b16213b51bdfaece0524c1c1bc30c63c484"
            ],
-            "version": "==2.4.7"
+            "version": "==3.0.7"
        },
        "pytz": {
            "hashes": [
-                "sha256:83a4a90894bf38e243cf052c8b58f381bfe9a7a483f6a9cab140bc7f702ac4da",
-                "sha256:eb10ce3e7736052ed3623d49975ce333bcd712c7bb19a58b9e2089d4057d0798"
+                "sha256:3672058bc3453457b622aab7a1c3bfd5ab0bdae451512f6cf25f64ed37f5b87c",
+                "sha256:acad2d8b20a1af07d4e4c9d2e9285c5ed9104354062f275f3fcd88dcef4f1326"
            ],
-            "version": "==2021.1"
+            "version": "==2021.3"
        },
        "requests": {
            "hashes": [
-                "sha256:27973dd4a904a4f13b263a19c866c13b92a39ed1c964655f025f3f8d3d75b804",
-                "sha256:c210084e36a42ae6b9219e00e48287def368a26d03a048ddad7bfee44f75871e"
+                "sha256:68d7c56fd5a8999887728ef304a6d12edc7be74f1cfa47714fc8b414525c9a61",
+                "sha256:f22fa1e554c9ddfd16e6e41ac79759e17be9e492b3587efa038054674760e72d"
            ],
-            "version": "==2.25.1"
+            "version": "==2.27.1"
        },
        "six": {
            "hashes": [
@ -169,18 +206,18 @@
        },
        "snowballstemmer": {
            "hashes": [
-                "sha256:b51b447bea85f9968c13b650126a888aabd4cb4463fca868ec596826325dedc2",
-                "sha256:e997baa4f2e9139951b6f4c631bad912dfd3c792467e2f03d7239464af90e914"
+                "sha256:09b16deb8547d3412ad7b590689584cd0fe25ec8db3be37788be3810cbf19cb1",
+                "sha256:c8e1716e83cc398ae16824e5572ae04e0d9fc2c6b985fb0f900f5f0c96ecba1a"
            ],
-            "version": "==2.1.0"
+            "version": "==2.2.0"
        },
        "sphinx": {
            "hashes": [
-                "sha256:429e3172466df289f0f742471d7e30ba3ee11f3b5aecd9a840480d03f14bcfe5",
-                "sha256:c4cb17ba44acffae3d3209646b6baec1e215cad3065e852c68cc569d4df1b9f8"
+                "sha256:048dac56039a5713f47a554589dc98a442b39226a2b9ed7f82797fcb2fe9253f",
+                "sha256:32a5b3e9a1b176cc25ed048557d4d3d01af635e6b76c5bc7a43b0a34447fbd45"
            ],
            "index": "pypi",
-            "version": "==1.8.3"
+            "version": "==4.3.1"
        },
        "sphinx-autobuild": {
            "hashes": [
@ -198,6 +235,41 @@
            "index": "pypi",
            "version": "==0.2.12"
        },
+        "sphinxcontrib-applehelp": {
+            "hashes": [
+                "sha256:806111e5e962be97c29ec4c1e7fe277bfd19e9652fb1a4392105b43e01af885a",
+                "sha256:a072735ec80e7675e3f432fcae8610ecf509c5f1869d17e2eecff44389cdbc58"
+            ],
+            "version": "==1.0.2"
+        },
+        "sphinxcontrib-devhelp": {
+            "hashes": [
+                "sha256:8165223f9a335cc1af7ffe1ed31d2871f325254c0423bc0c4c7cd1c1e4734a2e",
+                "sha256:ff7f1afa7b9642e7060379360a67e9c41e8f3121f2ce9164266f61b9f4b338e4"
+            ],
+            "version": "==1.0.2"
+        },
+        "sphinxcontrib-htmlhelp": {
+            "hashes": [
+                "sha256:d412243dfb797ae3ec2b59eca0e52dac12e75a241bf0e4eb861e450d06c6ed07",
+                "sha256:f5f8bb2d0d629f398bf47d0d69c07bc13b65f75a81ad9e2f71a63d4b7a2f6db2"
+            ],
+            "version": "==2.0.0"
+        },
+        "sphinxcontrib-jsmath": {
+            "hashes": [
+                "sha256:2ec2eaebfb78f3f2078e73666b1415417a116cc848b72e5172e596c871103178",
+                "sha256:a9925e4a4587247ed2191a22df5f6970656cb8ca2bd6284309578f2153e0c4b8"
+            ],
+            "version": "==1.0.1"
+        },
+        "sphinxcontrib-qthelp": {
+            "hashes": [
+                "sha256:4c33767ee058b70dba89a6fc5c1892c0d57a54be67ddd3e7875a18d14cba5a72",
+                "sha256:bd9fc24bcb748a8d51fd4ecaade681350aa63009a347a8c14e637895444dfab6"
+            ],
+            "version": "==1.0.3"
+        },
        "sphinxcontrib-serializinghtml": {
            "hashes": [
                "sha256:352a9a00ae864471d3a7ead8d7d79f5fc0b57e8b3f95e9867eb9eb28999b92fd",
@ -205,13 +277,6 @@
            ],
            "version": "==1.1.5"
        },
-        "sphinxcontrib-websupport": {
-            "hashes": [
-                "sha256:4edf0223a0685a7c485ae5a156b6f529ba1ee481a1417817935b20bde1956232",
-                "sha256:6fc9287dfc823fe9aa432463edd6cea47fa9ebbf488d7f289b322ffcfca075c7"
-            ],
-            "version": "==1.2.4"
-        },
        "tornado": {
            "hashes": [
                "sha256:0a00ff4561e2929a2c37ce706cb8233b7907e0cdc22eab98888aca5dd3775feb",
@ -260,11 +325,11 @@
        },
        "urllib3": {
            "hashes": [
-                "sha256:753a0374df26658f99d826cfe40394a686d05985786d946fbe4165b5148f5a7c",
-                "sha256:a7acd0977125325f516bda9735fa7142b909a8d01e8b2e4c8108d0984e6e0098"
+                "sha256:000ca7f471a233c2251c6c7023ee85305721bfdf18621ebff4fd17a8653427ed",
+                "sha256:0e7c33d9a63e7ddfcb86780aac87befc2fbddf46c58dbb487e0855f7ceec283c"
            ],
            "index": "pypi",
-            "version": "==1.26.5"
+            "version": "==1.26.8"
        }
    },
    "develop": {}
--- a/docs/source/getting-started/app-architecture.rst
+++ b/docs/source/getting-started/app-architecture.rst
@ -155,6 +155,7 @@ Another example, showing how to *update* ledger state, is how we exercise the ``

 .. literalinclude:: code/templates-tarball/create-daml-app/ui/src/components/MainView.tsx
  :language: tsx
+  :force:
  :start-after: // FOLLOW_BEGIN
  :end-before: // FOLLOW_END

--- a/docs/source/getting-started/first-feature.rst
+++ b/docs/source/getting-started/first-feature.rst
@ -120,6 +120,7 @@ Again we show the entire component here; copy this into a new ``MessageEdit.tsx`

 .. literalinclude:: code/templates-tarball/create-daml-app/ui/src/components/MessageEdit.tsx
  :language: tsx
+  :force:
  :start-after: // MESSAGEEDIT_BEGIN
  :end-before: // MESSAGEEDIT_END

--- a/docs/theme/docs/conf.py
+++ b/docs/theme/docs/conf.py
@ -176,6 +176,6 @@ texinfo_documents = [
 # Import the Daml lexer
 def setup(sphinx):
    from pygments_daml_lexer import DAMLLexer
-    sphinx.add_lexer("daml", DAMLLexer())
+    sphinx.add_lexer("daml", DAMLLexer)
    from typescript import TypeScriptLexer
-    sphinx.add_lexer("tsx", TypeScriptLexer())
+    sphinx.add_lexer("tsx", TypeScriptLexer)
--- a/nix/bazel.nix
+++ b/nix/bazel.nix
@ -93,24 +93,10 @@ let shared = rec {
        sha256 = "0p1yls8pplfg59wzmb96m3pjcyr3202an1rcr5wn2jwqhqvqi4ll";
      };
      doCheck = false;
-      buildInputs = [sphinx183];
+      buildInputs = [pkgs.python3Packages.sphinx];
  } ;

-  # sphinx 2.2.2 causes build failures of //docs:pdf-docs.
-  # We override here rather than in nixpkgs.nix since GHC depends on sphinx
-  # and we don’t want to rebuild that unnecessarily.
-  sphinx183 = pkgs.python3Packages.sphinx.overridePythonAttrs (attrs: rec {
-    version = "1.8.3";
-    doCheck = false;
-    src = pkgs.fetchFromGitHub {
-      owner = "sphinx-doc";
-      repo = "sphinx";
-      rev = "v${version}";
-      sha256 = "1hkqi5kzs85idv1w85qdl1bb2fwh7ccmgp6m860kzpkrl55149y8";
-    };
-  });
-
-  sphinx183-exts = sphinx183.overridePythonAttrs (attrs: rec {
+  sphinx-exts = pkgs.python3Packages.sphinx.overridePythonAttrs (attrs: rec {
    propagatedBuildInputs = attrs.propagatedBuildInputs ++ [sphinx-copybutton];
  });

--- a/nix/default.nix
+++ b/nix/default.nix
@ -125,10 +125,10 @@ in rec {
      python3 = python3;
    };

-    sphinx-build      = sphinx183;
-    sphinx-quickstart = sphinx183;
+    sphinx-build      = sphinx;
+    sphinx-quickstart = sphinx;

-    sphinx183 = bazel_dependencies.sphinx183-exts;
+    sphinx = bazel_dependencies.sphinx-exts;

    convert = bazel_dependencies.imagemagick;