Sphinx-Bazel: rules inside sphinx

Sphinx-Bazel is an extension for the Sphinx documentation generator and allows the manual or automated documentation of following Bazel objects inside any Sphinx project:

Bazel object Manual documentation Automated documentation
Workspace bazel:workspace autobazel-workspace
└ Package bazel:package autobazel-package
   └ Target bazel:target autobazel-target
      ├ Rule bazel:rule autobazel-rule
      │ └ Attr. bazel:attribute autobazel-attribute
      ├ Macro bazel:macro autobazel-macro
      └ Impl. bazel:implementation autobazel-implementation

Sphinx-Bazel supports and renders rst-syntax (reStructuredText) in Docstrings of the files WORKSPACE, BUILD and any target with file-extension .bzl. It also parses the doc attribute from rule-definitions.

Automated documentation

.. autobazel-workspace:: ./bazel_example
   :packages:

Result

hello_world_workspace (./bazel_example)

My workspace description

# Some python code
print("awesome")
//main

MAIN package: does awesome things.

//lib

LIB package: provides awesome stuff.

Please take a look into Autobazel for the complete documentation.

Manual documentation

.. bazel:workspace:: my_workspace
   :path: c:\workspaces\project_x

   Stores *files* and everything else.

.. bazel:package:: //main
   :workspace:

   Stores some code

.. bazel:target:: //main:build
   :workspace_path:

   This **Bazel** target builds my sources.

Result

my_workspace (c:\workspaces\project_x)

Stores files and everything else.

//main
workspace: my_workspace

Stores some code.

//main:build
workspace path: c:\workspaces\project_x

This Bazel target builds my sources.

See Bazel domain for the complete documentation.

Motivation

This Sphinx extension is based on the needs of a software development team inside a german automotive company.

The project team was searching a small and practical way to add project-specific information (like requirements, test-cases, user manuals) to Bazel objects and accumulate this information inside a single sphinx project.

Sphinx-Bazel is part of a software bundle, which was designed to support the development of ISO 26262 compliant software. Other tools are: sphinx-need, sphinx-test-reports and tox-envreport.