.. _bazel-macros:

Bazel macro: ``docs``
=====================

The ``docs`` macro defined in ``docs.bzl`` is a convenience wrapper
that creates a small set of Bazel targets
to build, verify and preview the project's Sphinx documentation,
and to create a Python virtual environment for IDE support (Esbonio).

See :doc:`commands <commands>` for the targets/commands it creates.

The macro must be called from the repository root package.

Minimal example (root ``BUILD``)
--------------------------------

.. code-block:: python

   load("//:docs.bzl", "docs")

   docs(
       source_dir = "docs",
       data = [
           # labels to any extra tools or data you want included
           # e.g. "//:needs_json" or other tool targets
       ],
       deps = [
           # additional bazel labels providing Python deps or other runfiles
       ],
   )

- ``source_dir`` (string, default: ``"docs"``)
  Path (relative to repository root) to your Sphinx source directory. This is the folder
  that contains your ``conf.py`` and the top-level ReST/markdown sources.

- ``data`` (list of bazel labels)
  Extra runfiles / data targets that should be made available to the documentation targets.
  Typical entries are targets that generate or provide external data used by the docs, for
  example a ``:needs_json`` producer. The items in ``data`` are added to the py_binaries and
  to the Sphinx tooling so they are available at build time.

- ``deps`` (list of bazel labels)
  Additional Bazel dependencies to add to the Python binaries and the virtual environment
  target. Use this to add project-specific Python packages or extension libraries the docs
  build requires.

Edge cases
----------

- If your Sphinx ``conf.py`` expects files generated by other Bazel targets, make sure those
  targets are included in the ``data`` list so they are available to the build driver.
- The experimental "combo" targets rewrite some ``data`` labels for combined builds; those
  are intended for advanced use and are optional for normal doc workflows.