https://pantsbuild.org/ logo
Join Slack
Powered by
First is doc building: currently we use `nox` to b...
# general
a
First is doc building: currently we use 
nox
to build our docs (a single docset for the whole monorepo), which basically implies starting a new virtualenv, installing sphinx and a couple of things and running 
sphinx-build
. This command needs to be able to load the libraries, as we have all sorts of autodocs features. I have been thinking on how to achieve that with pants and I guess I should create a new target that would be 
sphinx_docs
and it would have all the libraries as dependencies. However, it seems strange that this has never come up (I have searched slack to no avail) so I thought I’d ask first.
a
hi im new to pants, so not sure to much of existing ecosytem i am however looking to build out some docs using sphinx/pydoc etc i just landed a (beta) readme creater in our repo, and im thinking to do something similar for building out sphinx docs
h
Hi! @adorable-engine-71736 would love to hear how you designed your readme implementation
Re sphinx, so you're using it to generate docs out of docstrings in .py files? Or are there also other inputs?
(that was a question for either of you...)
a
i was thinking to get some kind of pydoc from the doc strings i was thinking other info, but at least partly auto-generated (eg with package data etc) the readme implementation is here https://github.com/envoyproxy/pytooling/pull/96/files ive used it as a bit of crash course in learning pants so view it as beta 8/
a
this is correct
I use 
sphinx-apidoc
and then 
automodule
and the like
so it’s usually easy to build
but you need all the libraries to be available
h
The reason I ask is that maybe you don't need a special target type, and instead you run a new 
docgen
goal on the existing python_library targets
So like 
./pants docgen path/to/targets::
or whatever
➕ 1
This could work just like how linters work
They don't require a special target type
So I'm trying to figure out what the perceived need for a 
sphinx_docs
target is
a
i have a 
sphinx_runner
that i currently use in bazel for the main envoy docs
basically bazel collects up configured tarballs from different parts of the repo and feeds the tarball/s to the runner to turn into html (in this case)
this does a lot of bazel stuff eg turning protobuf -> api
for the tooling site im working on i mostly want a way to ~declaratively (/minimally) express the structure of the repo -> collection of pydoc/general documentation
i didnt think much beyond that
a
yes, a new goal instead could make sense. The reason I thought of new targets is because it’s a single unified set of docs, and therefore they are all generated together, so I don’t see how that could work running a new goal on each library
a
im gonna look a bit further at docgen - its not installed by default, and google doesnt turn up much in the way of useful results
a
it used to be in pants v1 I think, but I don;t see it in v2?
h
Yeah, it doesn't exist, I was suggesting creating it 🙂
And I guess borrowing the name from v1, I didn't even remember that it existed there
a
so im doing some further work on my readme goal atm, and my thought was that once that was ~complete i would hack something out of it to generate rst files and feed to sphinx
im just getting used to pants dev so it will take me some time, but if there is anything useful im more than happy to share, or to contribute to a common effort
i think being able to generate/validate docs and readme are v useful features
h
very useful, and we'd love to have your contributions! We're happy to help with the plugin API etc.
Open in Slack
PreviousNext
Powered by