kaycebasques commented 1 month ago

🐞 bug report

Affected Rule

sphinx_docs_library

Is this a regression?

No. I don't believe sphinx_docs_library has ever supported this attribute but it seems like it should.

Description

We use the literalinclude directive to pull in snippets of code from C++ files into our reStructuredText documentation. It seems like sphinx_docs_library should allow us to specify data dependencies alongside reStructuredText source files.

sphinx_docs_library(
    name = "docs",
    srcs = [
        "backends.rst",
        "docs.rst",
    ],
    data = [
        "examples/basic.cc",
        "examples/once_send_recv.cc",
    ],
    # ...
)

Adding data attribute to our sphinx_docs_library invocations throws errors, however.

literalinclude example: https://cs.opensource.google/pigweed/pigweed/+/385019a0292797dd63f00f008efe36d52d4d698a:pw_async2/docs.rst;l=27;bpv=1

🔬 Minimal Reproduction

git clone https://pigweed.googlesource.com/pigweed/pigweed
cd pigweed
git fetch https://pigweed.googlesource.com/pigweed/pigweed refs/changes/12/240912/2 && git checkout -b change-240912 FETCH_HEAD
- this change should get checked out: https://pwrev.dev/240912
bazelisk build //docs/...

🔥 Exception or Error

ERROR: /home/kayce/pigweed/pigweed/pw_async2/BUILD.bazel:340:20: //pw_async2:docs: no such attribute 'data' in 'sphinx_docs_library' rule
ERROR: /home/kayce/pigweed/pigweed/pw_async2/BUILD.bazel:340:20: Cannot compute config conditions
ERROR: /home/kayce/pigweed/pigweed/docs/BUILD.bazel:27:12: Target '//pw_async2:docs' contains an error and its package is in error and referenced by '//docs:_docs/_sources'
Target //docs:sphinx-build failed to build
ERROR: Analysis of target '//docs:_docs/_sources' failed; build aborted: Analysis failed
INFO: Elapsed time: 0.115s, Critical Path: 0.01s
INFO: 1 process: 1 internal.
ERROR: Build did NOT complete successfully

🌍 Your Environment

Operating System:

(uname -a output)

Linux kayce0 6.9.10-1rodete5-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.9.10-1rodete5 (2024-09-04) x86_64 GNU/Linux

Output of bazel version:

Bazelisk version: v1.19.0
Build target: @@//src/main/java/com/google/devtools/build/lib/bazel:BazelServer
Build time: Thu Jan 01 00:00:00 1970 (0)
Build timestamp: Thu Jan 01 00:00:00 1970 (0)
Build timestamp as int: 0

Rules_python version:

v0.36.0

Anything else relevant?

this is how we added initial support for rules_python/sphinxdocs stuff last week: https://pwrev.dev/237877

tpudlik commented 1 month ago

@rickeylev FYI

rickeylev commented 1 month ago

You can just put the files in srcs.

The way sphinx works is it basically takes two inputs: the directory of stuff to process (which is expected to have the conf.py file) and the output format to use. The main work the rules do is just creating that directory and relocating all the input files to be under it. Unlike "regular" library targets (like for a programming language), there isn't any distinction between "source files some compiler processes" and "opaque data payloads". It's all just files being staged into a directory.

Also, in case it helps:

There is an implicit .run target that you can use to directly run sphinx. e.g. bazel run //docs:docs.run. This can be helpful to mimic as if you had directly run sphinx-build in a non-bazel context (e.g drop into pdb etc)
You can build the underlying "sources directory" target directly to see what the directory that is being fed into sphinx looks like. The name is internal, but its handy to see what is being materialized. I think the name is {name}/_sources. e.g. bazel build //docs:docs/_sources