Public usage of sphinxdocs

[castler]

Hi,

I was looking at https://github.com/agoessling/rules_sphinx to move it to bzlmod.

While doing so I figured out that the sphinx integration implemented by rules_python is way more advanced (and feature complete). I get some mixed signals when looking at sphinxdocs though. While it seems there is a public part, it cannot be all used publicly. Since https://github.com/bazelbuild/rules_python/blob/main/sphinxdocs/private/BUILD.bazel#L37 is only visible within rules_python and not publicly.

So my question is: is it intended and sphinxdocs shall not be used by users of rules_python?

Thanks!

[aignas]

The main intention was to not expose an API prematurely. I personaly would love to see this reused in other projects and rules_testing could use this too.

I think if you would be willing to give us feedback on what works and what doesn't and potentially help by contributing PRs if you have the time/willingness, then it would be definitely very appreciated.

But befare deciding on how we proceed, let's see what @rickeylev has to say.

[castler]

Sure! First usage was really pleasant!

I will test it a little more for our use-cases and can provide either feedback here or in form of issues (what you guys prefer).

[rickeylev]

Yeah, I'm fine with exposing it publicly as an unsupported/experimental API. I want to move rules_testing over to it, too. We can change those visibility settings to public and add some doc disclaimers about them.

the sphinx integration implemented by rules_python is way more advanced (and feature complete).

Thanks 😁!

What language(s) are you generating docs for?

[castler]

Yeah, I'm fine with exposing it publicly as an unsupported/experimental API. I want to move rules_testing over to it, too. We can change those visibility settings to public and add some doc disclaimers about them.

OK. I will prepare a PR.

What language(s) are you generating docs for?

We mainly use Sphinx to generate higher-level documentation (e.g. user-documentation, how-to guides, ...). But we also have C++ and Python code, but honestly did not yet generate docs for it with thinks. That might be a next interesting step!