https://pantsbuild.org/ logo
#general
Title
# general
a

astonishing-london-2419

09/15/2021, 8:52 AM
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

adorable-engine-71736

09/15/2021, 2:57 PM
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

happy-kitchen-89482

09/15/2021, 3:38 PM
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

adorable-engine-71736

09/15/2021, 3:54 PM
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

astonishing-london-2419

09/15/2021, 5:54 PM
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

happy-kitchen-89482

09/15/2021, 7:52 PM
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

adorable-engine-71736

09/15/2021, 8:02 PM
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

astonishing-london-2419

09/16/2021, 3:27 AM
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

adorable-engine-71736

09/16/2021, 7:36 AM
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

astonishing-london-2419

09/16/2021, 12:31 PM
it used to be in pants v1 I think, but I don;t see it in v2?
h

happy-kitchen-89482

09/16/2021, 3:44 PM
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

adorable-engine-71736

09/16/2021, 3:46 PM
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

happy-kitchen-89482

09/16/2021, 4:15 PM
very useful, and we'd love to have your contributions! We're happy to help with the plugin API etc.