docs: docgen python apis

[rickeylev]

Uses autodoc2 to generate Python documentation for runfiles and sphinx_bzl.

This provides some basic API doc for our Python code. They don't look particularly great,
yet, but we can work on how they look in another PR.

Also:

• Fixes position of license rule and extra space in license text
• Forces sphinx_rtd_theme >= 2.0. uv kept trying to downgrade it for some reason.
• Use directives markup to document the sphinx_bzl directives
• Add sphinx_run rule to make it easier to run Sphinx interactively for debugging

[aignas]

I see that there is Python API reference and Bazel API reference in https://rules-python--2149.org.readthedocs.build/en/2149/api-py/index.html

[rickeylev]

Yeah, I was torn about putting the py docs under api-py/ instead of api/py. What makes it a bit weird is autodoc will generate an index with a TOC entry.

I pushed a change to demo what it looks like under api/py instead: https://rules-python--2149.org.readthedocs.build/en/2149/api/py/sphinx_bzl/sphinx_bzl.bzl.html

If you look at the sidebar, you'll see:

• Python API Reference -> links to api/py/index
• runfiles -> links to api/py/runfiles/
• runfiles.runfiles
• sphinx_bzl
• sphinx_bzl.bzl
• //python/cc
• ...

Clicking on Python API Reference cause sit to expand to duplicates of the module names, which are already listed in the TOC. If you click on sphinx.bzl, the sidebar then does a weird thing where both the top-level sphinx.bzl name and the sphinx.bzl name under Python API Reference is highlighted. Oddly, the runfiles.runfiles entry doesn't do this. I'm guessing its some bug (or maybe WAI) in the sidebar code that gets confused when the same document is listed multiple times.

This is caused by the api/index TOC using :glob: ** to list all subdocuments recursively and api/py/index explicitly listing the direct sub documents.

• I'd really like everything under api/; just feels cleaner. But that sidebar highlighting thing bugged me so much.
• I mostly like the flat listing in the sidebar. It's a nice overview of everything. It reminds me of Javadoc's class listing, which is great for trying to find something.
• We could move all the bzl docs under api/bzl and have separate TOCs for api/py and api/bzl: api/index would do glob * (one star), api/bzl/index would do glob ** (recursive). That'll act about the same as having api-py, but with an extra layer of indentation in the sidebar (since it'll show it as an "expansion" of the higher level TOC).
• We could remove the TOC from the Python API index template. I was torn about this. It's kind of nice to have a page with just the python api listed out. It's duplicated in api/index, though, so losing it isn't a great lose.

Of all the alternatives, that last one is the most appealing.

WDYT?

[aignas]

Hmmm. I would love the TOC to be grouped by:

• rules_python bzl API
• runfiles library
• sphinxdocs bzl API
• sphinxdocs python API

It could be all grouped under a single API reference group. Maybe the initial split was good, its just the index page for the Python API was incomplete and I thought it was a bug, but know looking at this more it all makes sense. Maybe just adding a single statement that the docs are WIP would make it good enough for this PR. Then the docs would not look like some bug in the doc building.

[rickeylev]

I like that grouping. Autodoc2 only supports a single output directory, but rules_python and sphinxdocs can go into their own dirs. I'll rearrange things.

[rickeylev]

Ok, reorganized. PTAL

[aignas]

The new structure LGTM, is it possible to do some path remapping for old links to still work? I think that is a nice to have.

On the other hand, this refactor teaches but on the other hand we should be sharing permalinks when linking to our docs anyway.

[rickeylev]

I found a sphinx plugin that can generate redirect HTML files. I mapped the files that previously existing to redirect to their new locations.