sphinx_docs currently derives the Sphinx source directory from the path of its config label after materialising it into its private source tree.
This becomes problematic when the config is generated and the documentation source directory has the same name as another Bazel target.
Minimal example:
_generated_conf(
name = "generated_conf",
output_path = "docs/conf.py",
)
py_binary(
name = "docs",
# ...
)
sphinx_docs(
name = "needs_json",
config = ":generated_conf",
# ...
)Bazel rejects this because the generated output docs/conf.py is below the executable output docs:
One of the output paths '.../docs/conf.py' and '.../docs'
is a prefix of the other.
Using a generated config at another output path avoids the Bazel conflict, but then sphinx_docs materialises the config at that path in its private source tree and uses its parent as the Sphinx source directory. Consequently, the actual documentation sources are no longer under the selected source root.
Sphinx itself supports separating the source directory and configuration directory, but this separation is currently not expressible through sphinx_docs.
Expected behavior: a generated config should be usable without requiring its Bazel output path to be located below the documentation source directory.
sphinx_docscurrently derives the Sphinx source directory from the path of itsconfiglabel after materialising it into its private source tree.This becomes problematic when the config is generated and the documentation source directory has the same name as another Bazel target.
Minimal example:
Bazel rejects this because the generated output
docs/conf.pyis below the executable outputdocs:Using a generated config at another output path avoids the Bazel conflict, but then
sphinx_docsmaterialises the config at that path in its private source tree and uses its parent as the Sphinx source directory. Consequently, the actual documentation sources are no longer under the selected source root.Sphinx itself supports separating the source directory and configuration directory, but this separation is currently not expressible through
sphinx_docs.Expected behavior: a generated config should be usable without requiring its Bazel output path to be located below the documentation source directory.