Override generation of id & href attributes for API documentation

[bheberlein]

This will replace dots with underscores in qualified names of Python modules & functions (e.g. mypackage.mymodule.myfunc) during translation to HTML, allowing ScrollSpy to identify documented API members as navigation targets.

Addresses #1207 and fixes #1026.

[bheberlein]

Looks like some more work is needed here. It will replace dots in href attributes of links, which is a pretty big issue that I should have foreseen. I'll see if I can come up with a some edits that will modify attributes in a more targeted way.

[choldgraf]

Just a quick thought - this seems like a valuable improvement - though is this not something that should be improved at the autodoc level instead of at the theme level? It feels like something that any HTML theme would benefit from, rather than unique to the pydata theme, right?

[bheberlein]

@choldgraf yes, I think it's a fair point. Perhaps the right way to proceed is to open an issue with Sphinx.

[drammock]

closing because the proposed solution has migrated upstream.

[12rambau]

I agree this fix deserves to be send upstream but in the meantime @bheberlein offers a workaround that could solve the issue we face without waiting for autodoc to change (I think they are a bit overwelmed on Sphinx side). So untill this is solved (sphinx-doc/sphinx#11208) what about integrating this solution ?

[drammock]

So untill this is solved (sphinx-doc/sphinx#11208) what about integrating this solution ?

OK by me, it's been more than a month with no reply on the upstream issue. Please add # TODO comments in the source that link to the upstream issue and say when it's OK to remove the functions, so that periodically when people edit that file, they can do a quick check to see if it's still needed.

@12rambau I leave it to you to figure out if this should go in before or after #1271

[12rambau]

it can be done after as the translator.py file was already existing, it will be a small conflict.

[12rambau]

@bheberlein I've merged the latest refactoring in your branch. The API page seems to work as expected, solving the issue mentioned in the PR.

Before we merge it could you:

• reference the issue in Sphinx so that our future self know when to remove this workaround
• apply the linter on the branch

[12rambau]

Thank you very much for updating your PR. I really like the solution you find, all good from my side