purple-umbrella-89891
05/13/2022, 8:03 AMsphinx-build
and sphinx-apidoc
within it. Can this be written as a pants target?curved-television-6568
05/13/2022, 8:07 AMpurple-umbrella-89891
05/13/2022, 8:14 AMcurved-television-6568
05/13/2022, 8:16 AM./pants export
goal that creates a venv with your deps in it, that might be useful.purple-umbrella-89891
05/13/2022, 8:17 AMcurved-television-6568
05/13/2022, 8:18 AMpurple-umbrella-89891
05/13/2022, 10:25 AM# docs/build_doc.py
from pathlib import Path
import shutil
from sphinx.cmd.build import main as sphinx_build_main
from sphinx.ext.apidoc import main as sphinx_apidoc_main
def _stringify(iterable):
return [str(item) for item in iterable]
def main():
docs_dir = Path("docs")
build_dir = docs_dir / "build"
source_dir = docs_dir / "source"
all_opts = ["-d", build_dir / "doctrees", source_dir]
shutil.rmtree(build_dir, ignore_errors=True)
shutil.rmtree(source_dir / "_apidoc", ignore_errors=True)
sphinx_apidoc_main(_stringify(["-o", source_dir / "_apidoc", "."]))
sphinx_apidoc_main(_stringify(["-o", source_dir / "_apidoc", "source/mypkg"]))
sphinx_build_main(_stringify(["-b", "html", *all_opts, build_dir / "html"]))
if __name__ == '__main__':
main()
# docs/BUILD
pex_binary(
name="build_doc",
entry_point="build_doc.py",
dependencies=["//:poetry"], # Depend on all external dependencies
)
python_sources()
It needs to depend on everything because Sphinx actually imports the code to be documented. There is a solution with mocks, but didn't work for me, so I opted to have pants create a venv with all dependencies. With those files, the documentation can be built using ./pants run docs:build_doc
.
Maybe it can be useful to other people until there is native support.happy-kitchen-89482
05/13/2022, 3:28 PMancient-vegetable-10556
05/13/2022, 3:34 PMwitty-crayon-22786
05/13/2022, 3:58 PMhundreds-father-404
05/13/2022, 11:45 PM