I'm trying to generate API documentation, which re...
# general
I'm trying to generate API documentation, which requires several steps: 1. Run the Python app to export the schema: create a PEX file, and run it via
capturing the schema as a file 2. Run the doc generator on the schema to create a .html file: install (via NPM) the doc generator and run it on the output of above, all via
3. Package the .html file into an archive:
This mostly works, except I'm finding step 1 is... weird. The targets I'm using are, something like:
Copy code
# path/to/dir/BUILD
pex_binary(name="print-schema", ...)
    command="../../../path.to.dir/print-schema.pex > schema.graphql",
    tools=["python3.9", "bash"],
Questions: 1. Is it possible to have
run an in-repo Python file directly, pulling in appropriate internal and external dependencies? It'd be nifty to not need to set up the PEX file if we didn't need to 2. Is
tools=["python3.9", ...]
the right way to pull in Python to run the PEX? I have a feeling that it'll just be just pulling in whatever
executable happens to be on PATH (if there is one), rather than the interpreter Pants has gone to great efforts to choose for 'normal' `run`/`test` etc. of Python targets? 3. Is there a better way to refer to the root of the repo/find the dependency pulled into the
, beyond just
the right number of times?
Good questions! I’m hoping to take a closer look at
so this is a helpful use-case
This does sound like a good use-case for a plugin (since you want the pants-discovered Python, and you want to pull in dependencies)
But, to clarify the issue, what would be the workflow for this outside of Pants?
The equivalent script (with a venv and node modules set up “normally”, e.g. via poetry and npm) would be something like:
Copy code
python script/print-schema.py > schema.graphql # step 1
npx spectaql config.yaml # step 2
zip … # step 3
A (codegen?) plug-in sounds like it might indeed handle step 1 smoothly, but I'm not sure I could sell my team (or even myself) on replacing a single one-off line of shell with dozens-to-hundreds of lines of Python. Based on https://www.pantsbuild.org/docs/plugins-overview, we might also be signing up for additional maintenance/upgrade burden due to lack of stability (which, to be clear, I totally support: stable and powerful APIs are nice as a consumer but a pain as a maintainer 😅 ).
I think I'm hoping that
can act as an ad-hoc codegen plugin. I noticed https://github.com/pantsbuild/pants/issues/17345 too, and I think it makes this work less well too: changes to the PEX file in 1 that don't affect the schema end up rerunning step 2 anyway.
Yeah, this sounds like a good use case for
👍 1
I'm being a squeaky wheel (thanks for tolerating it!) and filed issues about those questions: 1/2 https://github.com/pantsbuild/pants/issues/17405 (arguably should be separate, but seems somewhat related) 3 https://github.com/pantsbuild/pants/issues/17404 I found
is substituted (🎉)
Thanks for filing these!