summary refs log tree commit diff
path: root/third_party/bazel/rules_haskell/docs
diff options
context:
space:
mode:
Diffstat (limited to 'third_party/bazel/rules_haskell/docs')
-rw-r--r--third_party/bazel/rules_haskell/docs/.gitignore1
-rw-r--r--third_party/bazel/rules_haskell/docs/BUILD.bazel46
-rw-r--r--third_party/bazel/rules_haskell/docs/conf.py41
-rw-r--r--third_party/bazel/rules_haskell/docs/haskell-use-cases.rst283
-rw-r--r--third_party/bazel/rules_haskell/docs/haskell.rst364
-rw-r--r--third_party/bazel/rules_haskell/docs/index.rst23
-rw-r--r--third_party/bazel/rules_haskell/docs/why-bazel.rst102
7 files changed, 0 insertions, 860 deletions
diff --git a/third_party/bazel/rules_haskell/docs/.gitignore b/third_party/bazel/rules_haskell/docs/.gitignore
deleted file mode 100644
index e35d8850c968..000000000000
--- a/third_party/bazel/rules_haskell/docs/.gitignore
+++ /dev/null
@@ -1 +0,0 @@
-_build
diff --git a/third_party/bazel/rules_haskell/docs/BUILD.bazel b/third_party/bazel/rules_haskell/docs/BUILD.bazel
deleted file mode 100644
index e21093c8ec6c..000000000000
--- a/third_party/bazel/rules_haskell/docs/BUILD.bazel
+++ /dev/null
@@ -1,46 +0,0 @@
-load("@io_bazel_skydoc//skylark:skylark.bzl", "skylark_doc")
-
-genrule(
-    name = "guide_html",
-    srcs = ["conf.py"] + glob(["*.rst"]),
-    outs = ["guide_html.zip"],
-    cmd = """
-    set -euo pipefail
-    # Nixpkgs_rules are pointing to every bins individually. Here
-    # we are extracting the /bin dir path to append it to the $$PATH.
-    CWD=`pwd`
-    sphinxBinDir=$${CWD}/$$(echo $(locations @sphinx//:bin) | cut -d ' ' -f 1 | xargs dirname)
-    dotBinDir=$${CWD}/$$(echo $(locations @graphviz//:bin) | cut -d ' ' -f 1 | xargs dirname)
-    zipBinDir=$${CWD}/$$(echo $(locations @zip//:bin) | cut -d ' ' -f 1 | xargs dirname)
-    PATH=$${PATH}:$${sphinxBinDir}:$${dotBinDir}:$${zipBinDir}
-    sourcedir=$$(dirname $(location conf.py))
-    builddir=$$(mktemp -d rules_haskell_docs.XXXX)
-    sphinx-build -M html $$sourcedir $$builddir -W -N -q
-    (cd $$builddir/html && zip -q -r $$CWD/$@ .)
-    rm -rf $$builddir
-    """,
-    tools = [
-        "@graphviz//:bin",
-        "@sphinx//:bin",
-        "@zip//:bin",
-    ],
-)
-
-skylark_doc(
-    name = "api_html",
-    srcs = [
-
-        # The order of these files defines the order in which the corresponding
-        # sections are presented in the docs.
-        "//haskell:haskell.bzl",
-        "//haskell:haddock.bzl",
-        "//haskell:lint.bzl",
-        "//haskell:toolchain.bzl",
-        "//haskell:protobuf.bzl",
-        "//haskell:cc.bzl",
-        "//haskell:repositories.bzl",
-        "//haskell:ghc_bindist.bzl",
-        "//haskell:nixpkgs.bzl",
-    ],
-    format = "html",
-)
diff --git a/third_party/bazel/rules_haskell/docs/conf.py b/third_party/bazel/rules_haskell/docs/conf.py
deleted file mode 100644
index acfe5dc7af88..000000000000
--- a/third_party/bazel/rules_haskell/docs/conf.py
+++ /dev/null
@@ -1,41 +0,0 @@
-project = 'rules_haskell'
-
-copyright = '2018, The rules_haskell authors'
-
-source_suffix = '.rst'
-
-extensions = [
-    'sphinx.ext.graphviz',
-    'sphinx.ext.todo',
-]
-
-master_doc = 'index'
-
-language = None
-
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
-
-pygments_style = 'sphinx'
-
-html_theme = 'alabaster'
-
-html_theme_options = {
-    'show_powered_by': False,
-    'github_user': 'tweag',
-    'github_repo': 'rules_haskell',
-    'github_banner': True,
-    'github_type': "star",
-    'show_related': False,
-    'note_bg': '#FFF59C',
-}
-
-html_show_sphinx = False
-
-todo_include_todos = True
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass).
-latex_documents = [
-    (master_doc, 'rules_haskell.tex', 'rules\\_haskell Documentation',
-     'Tweag I/O', 'manual'),
-]
diff --git a/third_party/bazel/rules_haskell/docs/haskell-use-cases.rst b/third_party/bazel/rules_haskell/docs/haskell-use-cases.rst
deleted file mode 100644
index a8c4340cf70f..000000000000
--- a/third_party/bazel/rules_haskell/docs/haskell-use-cases.rst
+++ /dev/null
@@ -1,283 +0,0 @@
-.. _use-cases:
-
-Common Haskell Build Use Cases
-==============================
-
-Picking a compiler
-------------------
-
-Unlike Bazel's native C++ rules, rules_haskell does not auto-detect
-a Haskell compiler toolchain from the environment. This is by design.
-We require that you declare a compiler to use in your ``WORKSPACE``
-file.
-
-There are two common sources for a compiler. One is to use the
-official binary distributions from `haskell.org`_. This is done using
-the `ghc_bindist`_ rule.
-
-The compiler can also be pulled from Nixpkgs_, a set of package
-definitions for the `Nix package manager`_. Pulling the compiler from
-Nixpkgs makes the build more hermetic, because the transitive closure
-of the compiler and all its dependencies is precisely defined in the
-``WORKSPACE`` file. Use `rules_nixpkgs`_ to do so (where ``X.Y.Z``
-stands for any recent release)::
-
-  load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
-
-  http_archive(
-      name = "io_tweag_rules_nixpkgs",
-      strip_prefix = "rules_nixpkgs-X.Y.Z",
-      urls = ["https://github.com/tweag/rules_nixpkgs/archive/vX.Y.Z.tar.gz"],
-  )
-
-  load(
-      "@io_tweag_rules_nixpkgs//nixpkgs:nixpkgs.bzl",
-      "nixpkgs_git_repository",
-      "nixpkgs_package"
-  )
-
-  nixpkgs_git_repository(
-      name = "nixpkgs",
-      revision = "18.09", # Any tag or commit hash
-  )
-
-  nixpkgs_package(
-      name = "ghc",
-      repositories = { "nixpkgs": "@nixpkgs//:default.nix" }
-      attribute_path = "haskell.compiler.ghc843", # Any compiler version
-      build_file = "@io_tweag_rules_haskell//haskell:ghc.BUILD",
-  )
-
-  register_toolchains("//:ghc")
-
-This workspace description specifies which Nixpkgs version to use,
-then exposes a Nixpkgs package containing the GHC compiler. The
-description assumes that there exists a ``BUILD`` file at the root of
-the repository that includes the following::
-
-  haskell_toolchain(
-    name = "ghc",
-    # Versions here and in WORKSPACE must match.
-    version = "8.4.3",
-    # Use binaries from @ghc//:bin to define //:ghc toolchain.
-    tools = ["@ghc//:bin"],
-  )
-
-.. _Bazel+Nix blog post: https://www.tweag.io/posts/2018-03-15-bazel-nix.html
-.. _Nix package manager: https://nixos.org/nix
-.. _Nixpkgs: https://nixos.org/nixpkgs/manual/
-.. _ghc_bindist: http://api.haskell.build/haskell/ghc_bindist.html#ghc_bindist
-.. _haskell.org: https://haskell.org
-.. _haskell_binary: http://api.haskell.build/haskell/haskell.html#haskell_binary
-.. _haskell_library: http://api.haskell.build/haskell/haskell.html#haskell_library
-.. _rules_nixpkgs: https://github.com/tweag/rules_nixpkgs
-
-Loading targets in a REPL
--------------------------
-
-Rebuilds are currently not incremental *within* a binary or library
-target (rebuilds are incremental across targets of course). Any change
-in any source file will trigger a rebuild of all source files listed
-in a target. In Bazel, it is conventional to decompose libraries into
-small units. In this way, libraries require less work to rebuild.
-Still, for interactive development full incrementality and fast
-recompilation times are crucial for a good developer experience. We
-recommend making all development REPL-driven for fast feedback when
-source files change.
-
-Every `haskell_binary`_ and every `haskell_library`_ target has an
-optional executable output that can be run to drop you into an
-interactive session. If the target's name is ``foo``, then the REPL
-output is called ``foo@repl``.
-
-Consider the following binary target::
-
-  haskell_binary(
-      name = "hello",
-      srcs = ["Main.hs", "Other.hs"],
-      deps = ["//lib:some_lib"],
-  )
-
-The target above also implicitly defines ``hello@repl``. You can call
-the REPL like this (requires Bazel 0.15 or later)::
-
-  $ bazel run //:hello@repl
-
-This works for any ``haskell_binary`` or ``haskell_library`` target.
-Modules of all libraries will be loaded in interpreted mode and can be
-reloaded using the ``:r`` GHCi command when source files change.
-
-Building code with Hackage dependencies (using Nix)
----------------------------------------------------
-
-Each Haskell library or binary needs a simple build description to
-tell Bazel what source files to use and what the dependencies are, if
-any. Packages on Hackage don't usually ship with `BUILD.bazel` files.
-So if your code depends on them, you either need to write a build
-description for each package, generate one (see next section), or
-decide not to use Bazel to build packages published on Hackage. This
-section documents one way to do the latter.
-
-Nix is a package manager. The set of package definitions is called
-Nixpkgs. This repository contains definitions for most actively
-maintained Cabal packages published on Hackage. Where these packages
-depend on system libraries like zlib, ncurses or libpng, Nixpkgs also
-contains package descriptions for those, and declares those as
-dependencies of the Cabal packages. Since these definitions already
-exist, we can reuse them instead of rewriting these definitions as
-build definitions in Bazel. See the `Bazel+Nix blog post`_ for a more
-detailed rationale.
-
-To use Nixpkgs in Bazel, we need `rules_nixpkgs`_. See `Picking
-a compiler`_ for how to import Nixpkgs rules into your workspace and
-how to use a compiler from Nixpkgs. To use Cabal packages from
-Nixpkgs, replace the compiler definition with the following::
-
-  nixpkgs_package(
-      name = "ghc",
-      repositories = { "nixpkgs": "@nixpkgs//:default.nix" },
-      nix_file = "//:ghc.nix",
-      build_file = "@io_tweag_rules_haskell//haskell:ghc.BUILD",
-  )
-
-This definition assumes a ``ghc.nix`` file at the root of the
-repository. In this file, you can use the Nix expression language to
-construct a compiler with all the packages you depend on in scope::
-
-  with (import <nixpkgs> {});
-
-  haskellPackages.ghcWithPackages (p: with p; [
-    containers
-    lens
-    text
-  ])
-
-Each package mentioned in ``ghc.nix`` can then be imported using
-`haskell_toolchain_library`_ in ``BUILD`` files.
-
-.. _haskell_toolchain_library: http://api.haskell.build/haskell/haskell.html#haskell_toolchain_library
-
-Building code with Hackage dependencies (using Hazel)
------------------------------------------------------
-
-.. todo::
-
-   Explain how to use Hazel instead of Nix
-
-Generating API documentation
-----------------------------
-
-The `haskell_doc`_ rule can be used to build API documentation for
-a given library (using Haddock). Building a target called
-``//my/pkg:mylib_docs`` would make the documentation available at
-``bazel-bin/my/pkg/mylib_docs/index/index.html``.
-
-Alternatively, you can use the
-``@io_tweag_rules_haskell//haskell:haskell.bzl%haskell_doc_aspect``
-aspect to ask Bazel from the command-line to build documentation for
-any given target (or indeed all targets), like in the following:
-
-.. code-block:: console
-
-  $ bazel build //my/pkg:mylib \
-      --aspects @io_tweag_rules_haskell//haskell:haskell.bzl%haskell_doc_aspect
-
-.. _haskell_doc: http://api.haskell.build/haskell/haddock.html#haskell_doc
-
-Linting your code
------------------
-
-The `haskell_lint`_ rule does not build code but runs the GHC
-typechecker on all listed dependencies. Warnings are treated as
-errors.
-
-Alternatively, you can directly check a target using
-
-.. code-block:: console
-
-  $ bazel build //my/haskell:target \
-      --aspects @io_tweag_rules_haskell//haskell:haskell.bzl%haskell_lint_aspect
-
-.. _haskell_lint: http://api.haskell.build/haskell/lint.html#haskell_lint
-
-Checking code coverage
-----------------------
-
-"Code coverage" is the name given to metrics that describe how much source 
-code is covered by a given test suite.  A specific code coverage metric 
-implemented here is expression coverage, or the number of expressions in 
-the source code that are explored when the tests are run.
-
-Haskell's ``ghc`` compiler has built-in support for code coverage analysis, 
-through the hpc_ tool. The Haskell rules allow the use of this tool to analyse 
-``haskell_library`` coverage by ``haskell_test`` rules. To do so, you have a 
-few options. You can add 
-``expected_covered_expressions_percentage=<some integer between 0 and 100>`` to
-the attributes of a ``haskell_test``, and if the expression coverage percentage
-is lower than this amount, the test will fail. Alternatively, you can add
-``expected_uncovered_expression_count=<some integer greater or equal to 0>`` to
-the attributes of a ``haskell_test``, and instead the test will fail if the
-number of uncovered expressions is greater than this amount. Finally, you could
-do both at once, and have both of these checks analyzed by the coverage runner.
-To see the coverage details of the test suite regardless of if the test passes
-or fails, add ``--test_output=all`` as a flag when invoking the test, and there 
-will be a report in the test output. You will only see the report if you
-required a certain level of expression coverage in the rule attributes.
-
-For example, your BUILD file might look like this: ::
-
-  haskell_library(
-    name = "lib",
-    srcs = ["Lib.hs"],
-    deps = [
-        "//tests/hackage:base",
-    ],
-  )
-
-  haskell_test(
-    name = "test",
-    srcs = ["Main.hs"],
-    deps = [
-        ":lib",
-        "//tests/hackage:base",
-    ],
-    expected_covered_expressions_percentage = 80,
-    expected_uncovered_expression_count = 10,
-  )
-
-And if you ran ``bazel coverage //somepackage:test --test_output=all``, you 
-might see a result like this: ::
-
-  INFO: From Testing //somepackage:test:
-  ==================== Test output for //somepackage:test:
-  Overall report
-  100% expressions used (9/9)
-  100% boolean coverage (0/0)
-      100% guards (0/0)
-      100% 'if' conditions (0/0)
-      100% qualifiers (0/0)
-  100% alternatives used (0/0)
-  100% local declarations used (0/0)
-  100% top-level declarations used (3/3)
-  =============================================================================
-
-Here, the test passes because it actually has 100% expression coverage and 0
-uncovered expressions, which is even better than we expected on both counts.
-
-There is an optional ``haskell_test`` attribute called
-``strict_coverage_analysis``, which is a boolean that changes the coverage
-analysis such that even having better coverage than expected fails the test.
-This can be used to enforce that developers must upgrade the expected test
-coverage when they improve it. On the other hand, it requires changing the
-expected coverage for almost any change.
-
-There a couple of notes regarding the coverage analysis functionality:
-
-- Coverage analysis currently is scoped to all source files and all
-  locally-built Haskell dependencies (both direct and transitive) for a given
-  test rule.
-- Coverage-enabled build and execution for ``haskell_test`` targets may take
-  longer than regular. However, this has not effected regular ``run`` /
-  ``build`` / ``test`` performance.
-
-.. _hpc: <http://hackage.haskell.org/package/hpc>
diff --git a/third_party/bazel/rules_haskell/docs/haskell.rst b/third_party/bazel/rules_haskell/docs/haskell.rst
deleted file mode 100644
index 353561111a21..000000000000
--- a/third_party/bazel/rules_haskell/docs/haskell.rst
+++ /dev/null
@@ -1,364 +0,0 @@
-.. _guide:
-
-Introduction to Bazel: Building a Haskell project
-=================================================
-
-In this tutorial, you'll learn the basics of building Haskell
-applications with Bazel. You will set up your workspace and build
-a simple Haskell project that illustrates key Bazel concepts, such as
-targets and ``BUILD.bazel`` files. After completing this tutorial, take
-a look at :ref:`Common Haskell build use cases <use-cases>` for
-information on more advanced concepts such as writing and running
-Haskell tests.
-
-What you'll learn
------------------
-
-In this tutorial you'll learn how to:
-
-* build a target,
-* visualize the project's dependencies,
-* split the project into multiple targets and packages,
-* control target visibility across packages,
-* reference targets through labels.
-
-Before you begin
-----------------
-
-To prepare for the tutorial, first `install Bazel`_ if you don't have
-it installed already. Then, retrieve the ``rules_haskell`` GitHub
-repository::
-
-  git clone https://github.com/tweag/rules_haskell/
-
-The sample project for this tutorial is in the ``tutorial``
-directory and is structured as follows::
-
-  rules_haskell
-  └── tutorial
-     ├── WORKSPACE
-     ├── main
-     │  ├── BUILD.bazel
-     │  └── Main.hs
-     └── lib
-        ├── BUILD.bazel
-        └── Bool.hs
-
-The first thing to do is to::
-
-  $ cd tutorial
-
-Build with Bazel
-----------------
-
-Set up the workspace
-^^^^^^^^^^^^^^^^^^^^
-
-Before you can build a project, you need to set up its workspace.
-A workspace is a directory that holds your project's source files and
-Bazel's build outputs. It also contains files that Bazel recognizes as
-special:
-
-* the ``WORKSPACE`` file, which identifies the directory and its
-  contents as a Bazel workspace and lives at the root of the project's
-  directory structure,
-
-* one or more ``BUILD.bazel`` files, which tell Bazel how to build different
-  parts of the project. (A directory within the workspace that
-  contains a ``BUILD.bazel`` file is a *package*. You will learn about
-  packages later in this tutorial.)
-
-To designate a directory as a Bazel workspace, create an empty file
-named ``WORKSPACE`` in that directory.
-
-When Bazel builds the project, all inputs and dependencies must be in
-the same workspace. Files residing in different workspaces are
-independent of one another unless linked, which is beyond the scope of
-this tutorial.
-
-Understand the BUILD file
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-It is recommended to use a ``.bazel`` extension for each ``BUILD`` file to
-avoid clashing with files or folders already using that name.
-
-A ``BUILD.bazel`` file contains several different types of instructions for
-Bazel. The most important type is the *build rule*, which tells Bazel
-how to build the desired outputs, such as executable binaries or
-libraries. Each instance of a build rule in the ``BUILD.bazel`` file is
-called a *target* and points to a specific set of source files and
-dependencies. A target can also point to other targets.
-
-Take a look at the ``BUILD.bazel`` file in the ``tutorial/lib`` directory::
-
-  haskell_library(
-      name = "booleans",
-      srcs = ["Bool.hs"],
-  )
-
-In our example, the ``booleans`` target instantiates the
-`haskell_library`_ rule. The rule tells Bazel to build a reusable
-(statically or dynamically linked) library from the ``Bool.hs`` source
-file with no dependencies.
-
-The attributes in the target explicitly state its dependencies and
-options. While the ``name`` attribute is mandatory, many are optional.
-For example, in the ``booleans`` target, ``name`` is self-explanatory,
-and ``srcs`` specifies the source file(s) from which Bazel builds the
-target.
-
-Build the project
-^^^^^^^^^^^^^^^^^
-
-Let's build your sample project. Run the following command::
-
-  $ bazel build //lib:booleans
-
-Notice the target label - the ``//lib:`` part is the location of our
-``BUILD.bazel`` file relative to the root of the workspace, and ``booleans``
-is what we named that target in the ``BUILD.bazel`` file. (You will learn
-about target labels in more detail at the end of this tutorial.)
-
-Bazel produces output similar to the following::
-
-  INFO: Found 1 target...
-  Target //lib:booleans up-to-date:
-    bazel-bin/lib/libZSbooleans/libZSbooleans.conf
-    bazel-bin/lib/libZSbooleans/package.cache
-  INFO: Elapsed time: 2.288s, Critical Path: 0.68s
-
-Congratulations, you just built your first Bazel target! Bazel places
-build outputs in the ``bazel-bin`` directory at the root of the
-workspace. Browse through its contents to get an idea for Bazel's
-output structure.
-
-Review the dependency graph
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-A successful build has all of its dependencies explicitly stated in
-the ``BUILD.bazel`` file. Bazel uses those statements to create the
-project's dependency graph, which enables accurate incremental builds.
-
-Let's visualize our sample project's dependencies. First, generate
-a text representation of the dependency graph (run the command at the
-workspace root)::
-
-  bazel query --nohost_deps --noimplicit_deps \
-    'deps(//lib:booleans)' --output graph
-
-The above command tells Bazel to look for all dependencies for the
-target ``//lib:booleans`` (excluding host and implicit dependencies)
-and format the output as a graph.
-
-Then, paste the text into GraphViz_.
-
-On Ubuntu, you can view the graph locally by installing GraphViz and the xdot
-Dot Viewer::
-
-  sudo apt update && sudo apt install graphviz xdot
-
-Then you can generate and view the graph by piping the text output above
-straight to xdot::
-
-  xdot <(bazel query --nohost_deps --noimplicit_deps \
-           'deps(//lib:booleans)' --output graph)
-
-As you can see, the first stage of the sample project has a single
-target that builds a single source file with no additional
-dependencies:
-
-.. digraph:: booleans
-
-   node [shape=box];
-   "//lib:booleans"
-   "//lib:booleans" -> "//lib:Bool.hs"
-   "//lib:Bool.hs"
-
-Now that you have set up your workspace, built your project, and
-examined its dependencies, let's add some complexity.
-
-Refine your Bazel build
------------------------
-
-While a single target is sufficient for small projects, you may want
-to split larger projects into multiple targets and packages to allow
-for fast incremental builds (that is, only rebuild what's changed) and
-to speed up your builds by building multiple parts of a project at
-once.
-
-Specify multiple build targets
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Let's split our sample project build into two targets. Take a look at
-the ``BUILD.bazel`` files in the ``tutorial/lib`` and ``tutorial/main``
-directories. The contents of both files could have been kept in
-a single ``BUILD.bazel`` as follows::
-
-  haskell_library(
-      name = "booleans",
-      srcs = ["Bool.hs"],
-  )
-
-  haskell_toolchain_library(name = "base")
-
-  haskell_binary(
-      name = "demorgan",
-      srcs = ["Main.hs"],
-      compiler_flags = ["-threaded"],
-      deps = [":base", ":booleans"],
-  )
-
-With this single ``BUILD.bazel`` file, Bazel first builds the ``booleans``
-library (using the `haskell_library`_ rule), then the ``demorgan``
-binary (which as an example uses the ``booleans`` library to check one
-of the De Morgan laws). The ``deps`` attribute in the ``demorgan``
-target tells Bazel that the ``:booleans`` library is required to build
-the ``demorgan`` binary. The binary also requires the ``base``
-built-in library that ships with GHC, to perform I/O among other
-things. Libraries like ``base``, ``bytestring`` and others that ship
-with GHC are special in that they are prebuilt outside of Bazel. To
-import them as regular targets, we use the `haskell_toolchain_library`_ rule.
-
-Let's build this new version of our project::
-
-  $ bazel build //main:demorgan
-
-Bazel produces output similar to the following::
-
-  INFO: Found 1 target...
-  Target //main:demorgan up-to-date:
-    bazel-bin/main/demorgan
-  INFO: Elapsed time: 2.728s, Critical Path: 1.23s
-
-Now test your freshly built binary::
-
-  $ bazel-bin/main/demorgan
-
-Or alternatively::
-
-  $ bazel run //main:demorgan
-
-If you now modify ``Bool.hs`` and rebuild the project, Bazel will
-usually only recompile that file.
-
-Looking at the dependency graph:
-
-.. digraph:: demorgan
-
-  node [shape=box];
-  "//main:demorgan"
-  "//main:demorgan" -> "//main:base\n//main:Main.hs"
-  "//main:demorgan" -> "//lib:booleans"
-  "//lib:booleans"
-  "//lib:booleans" -> "//lib:Bool.hs"
-  "//lib:Bool.hs"
-  "//main:base\n//main:Main.hs"
-
-You have now built the project with two targets. The ``demorgan``
-target builds one source file and depends on one other target
-(``//lib:booleans``), which builds one additional source file.
-
-Use multiple packages
-^^^^^^^^^^^^^^^^^^^^^
-
-Let’s now split the project into multiple packages.
-
-Notice that we actually have two sub-directories, and each contains
-a ``BUILD.bazel`` file. Therefore, to Bazel, the workspace contains two
-packages, ``lib`` and ``main``.
-
-Take a look at the ``lib/BUILD.bazel`` file::
-
-  haskell_library(
-      name = "booleans",
-      srcs = ["Bool.hs"],
-      visibility = ["//main:__pkg__"],
-  )
-
-And at the ``main/BUILD.bazel`` file::
-
-  haskell_toolchain_library(name = "base")
-
-  haskell_binary(
-      name = "demorgan",
-      srcs = ["Main.hs"],
-      compiler_flags = ["-threaded"],
-      deps = [":base", "//lib:booleans"],
-  )
-
-As you can see, the ``demorgan`` target in the ``main`` package
-depends on the ``booleans`` target in the ``lib`` package (hence the
-target label ``//lib:booleans``) - Bazel knows this through the
-``deps`` attribute.
-
-Notice that for the build to succeed, we make the ``//lib:booleans``
-target in ``lib/BUILD.bazel`` explicitly visible to targets in
-``main/BUILD.bazel`` using the ``visibility`` attribute. This is because by
-default targets are only visible to other targets in the same
-``BUILD.bazel`` file. (Bazel uses target visibility to prevent issues such
-as libraries containing implementation details leaking into public
-APIs.)
-
-You have built the project as two packages with three targets and
-understand the dependencies between them.
-
-Use labels to reference targets
--------------------------------
-
-In ``BUILD.bazel`` files and at the command line, Bazel uses *labels* to
-reference targets - for example, ``//main:demorgan`` or
-``//lib:booleans``. Their syntax is::
-
-  //path/to/package:target-name
-
-If the target is a rule target, then ``path/to/package`` is the path
-to the directory containing the ``BUILD.bazel`` file, and ``target-name`` is
-what you named the target in the ``BUILD.bazel`` file (the ``name``
-attribute). If the target is a file target, then ``path/to/package``
-is the path to the root of the package, and ``target-name`` is the
-name of the target file, including its full path.
-
-When referencing targets within the same package, you can skip the
-package path and just use ``//:target-name``. When referencing targets
-within the same ``BUILD.bazel`` file, you can even skip the ``//`` workspace
-root identifier and just use ``:target-name``.
-
-Further reading
----------------
-
-Congratulations! You now know the basics of building a Haskell project
-with Bazel. Next, read up on the most common :ref:`Common Haskell
-build use cases <use-cases>`. Then, check out the following:
-
-* `External Dependencies`_ to learn more about working with local and
-   remote repositories.
-
-* The `Build Encyclopedia`_ to learn more about Bazel.
-
-* The `C++ build tutorial`_ to get started with building C++
-  applications with Bazel.
-
-* The `Java build tutorial`_ to get started with building Java
-  applications with Bazel.
-
-* The `Android application tutorial`_ to get started with building
-  mobile applications for Android with Bazel.
-
-* The `iOS application tutorial`_ to get started with building mobile
-  applications for iOS with Bazel.
-
-Happy building!
-
-.. note:: This tutorial is adapted from the Bazel `C++ build tutorial`_.
-
-.. _install Bazel: https://docs.bazel.build/versions/master/install.html
-.. _haskell_binary: http://api.haskell.build/haskell/haskell.html#haskell_binary
-.. _haskell_toolchain_library: http://api.haskell.build/haskell/haskell.html#haskell_toolchain_library
-.. _haskell_library: http://api.haskell.build/haskell/haskell.html#haskell_library
-.. _graphviz: https://www.graphviz.org/
-.. _external dependencies: https://docs.bazel.build/versions/master/external.html
-.. _build encyclopedia: https://docs.bazel.build/versions/master/be/overview.html
-.. _C++ build tutorial: https://docs.bazel.build/versions/master/tutorial/cpp.html
-.. _Java build tutorial: https://docs.bazel.build/versions/master/tutorial/java.html
-.. _Android application tutorial: https://docs.bazel.build/versions/master/tutorial/android-app.html
-.. _iOS application tutorial: https://docs.bazel.build/versions/master/tutorial/ios-app.html
diff --git a/third_party/bazel/rules_haskell/docs/index.rst b/third_party/bazel/rules_haskell/docs/index.rst
deleted file mode 100644
index f9292871ef55..000000000000
--- a/third_party/bazel/rules_haskell/docs/index.rst
+++ /dev/null
@@ -1,23 +0,0 @@
-.. meta::
-   :description: User guide for building Haskell code with Bazel.
-
-Build Haskell Using Bazel
-=========================
-
-Bazel_ is a tool for automating the *building* and the *testing* of
-software. Follow :ref:`this guide <guide>` to get started building
-small Haskell projects using Bazel. For a deeper dive and solutions to
-more advanced use cases, see :ref:`Common Haskell Build Use Cases
-<use-cases>`. Refer to the `Bazel documentation`_ for more about
-Bazel.
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
-
-   why-bazel
-   haskell
-   haskell-use-cases
-
-.. _Bazel: https://bazel.build
-.. _Bazel documentation: https://docs.bazel.build/versions/master/getting-started.html
diff --git a/third_party/bazel/rules_haskell/docs/why-bazel.rst b/third_party/bazel/rules_haskell/docs/why-bazel.rst
deleted file mode 100644
index 2ad4bc598be3..000000000000
--- a/third_party/bazel/rules_haskell/docs/why-bazel.rst
+++ /dev/null
@@ -1,102 +0,0 @@
-.. _why-bazel:
-
-Is Bazel right for me?
-======================
-
-Nearly as many build tools exist as there are programming languages
-out there. C++ has Autotools_/Make_, CMake_ and many others. Java has
-Ant_, Maven_, Gradle_ and several more. Haskell has Cabal_, Stack_,
-Shake_ and several more. Each of these originated in a given language
-community but are in some cases generic enough to support building any
-language. Are any of them the right choice for your use case? Should
-you be combining several systems? That's what this document should
-help you answer.
-
-Rule of thumb
--------------
-
-If a combination of the following apply, then you're better off using
-Cabal_ or Stack_:
-
-* your project is an independently publishable single library, or
-  small set of libraries;
-* your project is open source code and has at most small static
-  assets (hence publishable on Hackage);
-* your project is nearly entirely Haskell code with perhaps a little
-  bit of C;
-* your project has many dependencies on other packages found on
-  Hackage but few if any system dependencies (like zlib, libpng etc);
-
-Bazel works well for the following use cases:
-
-* projects that cannot be hosted on Hackage (games with large static
-  assets, proprietary code etc);
-* projects with a very large amount of code hosted in a single
-  repository;
-* projects in which you or your team are writing code in two or more
-  languages (e.g. Haskell/PureScript, or Haskell/Java, or
-  Haskell/C++/FORTRAN);
-
-Rationale
----------
-
-For all the benefits it can bring, Bazel also has an upfront cost.
-Don't pay that cost if the benefits don't justify it.
-
-If you don't have much code to build, any build tool will do. Build
-issues like lack of complete reproducibility are comparatively easier
-to debug, and working around build system bugs by wiping the entire
-build cache first is entirely viable in this particular case. So might
-as well use low-powered Haskell-native build tools that ship with GHC.
-You won't *need* sandboxed build actions to guarantee build system
-correctness, completely hermetic builds for good reproducibility,
-build caching, test result caching or distributed builds for faster
-build and test times. Those features start to matter for larger
-projects, and become essential for very large monorepos_.
-
-Why exactly do these features matter?
-
-* **Hermetic builds** are builds that do not take any part of the
-  host's system configuration (set of installed system libraries and
-  their versions, content of ``/etc``, OS version, etc) as an input.
-  If all build actions are deterministic, hermeticity guarantees that
-  builds are reproducible anywhere, anytime. More developers on
-  a project means more subtly different system configurations to cope
-  with. The more system configurations, the more likely that the build
-  will fail in one of these configurations but not in others... Unless
-  the build is completely hermetic.
-* **Sandboxing build actions** guarantees that all inputs to all build
-  actions are properly declared. This helps prevent build system
-  correctness bugs, which are surprisingly and exceedingly common in
-  most non-sandboxing build systems, especially as the build system
-  becomes more complex. When a build system *might* be incorrect,
-  users regularly have to wipe the entire build cache to work around
-  issues. As the codebase becomes very large, rebuilding from scratch
-  can cost a lot of CPU time.
-* **Distributed build caches** make building the code from a fresh
-  checkout trivially fast. Continuous integration populates the build
-  cache at every branch push, so that building all artifacts from
-  fresh checkouts seldom needs to actually build anything at all
-  locally. In the common case, builds become network-bound instead of
-  CPU-bound.
-* **Distributed build action execution** mean that average build times
-  can stay constant even as the codebase grows, because you can
-  seamlessly distribute the build on more machines.
-* **Test result caching** is the key to keeping continuous
-  integration times very low. Only those tests that depend on code
-  that was modified need be rerun.
-
-On their own hermetic and sandboxed builds can already save quite
-a few headaches. But crucially, without them one can't even hope to
-have any of the other features that follow them above.
-
-.. _Autotools: https://en.wikipedia.org/wiki/GNU_Build_System
-.. _Make: https://en.wikipedia.org/wiki/Make_(software)
-.. _CMake: https://cmake.org/
-.. _Ant: https://ant.apache.org/
-.. _Maven: https://maven.apache.org/index.html
-.. _Gradle: https://gradle.org/
-.. _Cabal: https://www.haskell.org/cabal/
-.. _Stack: http://haskellstack.org/
-.. _Shake: https://shakebuild.com/
-.. _monorepos: https://en.wikipedia.org/wiki/Monorepo