Setup#

⚠️ Only valid for docs-as-code v1.x.x.

Overview#

docs-as-code allows you to easily integrate Sphinx documentation generation into your Bazel build system. It provides a collection of utilities and extensions specifically designed to enhance documentation capabilities in S-CORE.

Features#

  • Seamless integration with Bazel build system

  • S-CORE process compliance

  • Support for PlantUML diagrams

  • Source code linking capabilities

  • S-CORE layouts and themes

Installation#

1. /MODULE.bazel file#

Add the module to your MODULE.bazel file:

bazel_dep(name = "score_docs_as_code", version = "0.2.7")

And make sure to also add the S-core Bazel registry to your .bazelrc file

common --registry=https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/
common --registry=https://bcr.bazel.build

2. /BUILD file#

load("@score_docs_as_code//docs.bzl", "docs")

docs(
    source_dir = "<your sphinx source dir>",
    data = [
        "@other_repo:needs_json",  # Optional, if you have dependencies
    ],
)

Configuration Options#

The docs() macro accepts the following arguments:

Parameter

Description

Required

source_dir

Directory of documentation source files (RST, MD)

Yes

data

List of needs_json targets that should be included in the documentation

No

3. Copy conf.py#

Copy the conf.py file from the docs-as-code module to your source_dir.

4. Run a documentation build:#

bazel run //:docs

5. Access your documentation at#

/_build/index.html