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-needs,
sphinx-test-reports,
tox-envreport and
metric-farmer.
Contents¶
- Quickstart
- Bazel domain
- Autobazel
- Changelog