I saw that there'd been a small effort to add sphinx documentation generation to pants a few months back but it got reverted - is there interest in moving forward on that / what would be involved?

I would be delighted to see someone take that on. Thank you for considering it. We've just had too many other priorities for that one to percolate up to the top of the list. But it would be very helpful to be liberated from the confines imposed by our current dependence on readme.com. @ancient-vegetable-10556@hundreds-father-404 would be the best people to fill you in on what would be involved. They did a pretty comprehensive evaluation of the docs just a couple months ago.

yeah, using sphinx has been a pain point in my org before I joined (so i don't have much context), but I think the big hurdle was just in getting it to run, so having pants supply that part would make adding doc generation an easier sell and I've done some work on pants before and don't mind contributing some time

Oooh yes, getting help with in-Pants support for Sphinx would be great. @hundreds-father-404 was responsible for the work you saw reverted, so I’ll defer to them before coming in myself

Hi! The reasons I reverted it are a) we had a flaky test I couldn't figure out, and b) we weren't confident enough on the target modeling and figured it'd be better to have pantsbuild/pants dogfood Sphinx first I'd love to see Sphinx support added. I could see two directions: 1. Restore what I had, but figure out why it was a flaky test, or 2. Start from scratch with a design of what this should be, particularly how to model the target

If going for 2) is there another part of pants that exemplar of how to approach that?

Probably not - the specific modeling I'm referring to is the decision in https://github.com/pantsbuild/pants/pull/15512 to use

sphinx_project

for multiple files. I think it's sensible at least for something experimental, and will make progress on the project I'd likely recommend trying to restore https://github.com/pantsbuild/pants/pull/15512, and get the test to not be flaky Then maybe figuring out how to do in-repo docs is the next priority

great, thanks!

feel free to ask for help along the way, including if pair programming would help! @ancient-vegetable-10556 and I really want to use Sphinx for pantsbuild/pants itself, only haven't had the bandwidth