Replace dots with underscores in id and href attributes for generated HTML documentation

[bheberlein]

Is your feature request related to a problem? Please describe.
When generating HTML documentation with autodoc and sphinx-build, nodes representing documented Python objects (e.g. <section> tags for modules & submodules, <dt> & <dd> tags for function & method signatures) are assigned id attributes that may contain dots. Likewise, the href of any reference nodes pointing to those nodes will also contain dots. Dots are not valid for JavaScript identifiers, and will break things like ScrollSpy. See the related issue with PyData Sphinx theme.

This might be considered a bug, although the presence of dots is not strictly invalid in HTML. But since HTML documentation is generally intended to be served over a web interface, it should be able to play nicely with modern web ecosystems.

Describe the solution you'd like
HTMLTranslator classes should replace dots with underscores when assigning ids of nodes representing autodoc'd Python members, and the refuri and anchorname attributes of any reference nodes pointing to those members. Personally I think this should be the default behavior, but it would be acceptable to add an option (e.g. to sphinx-build) that would allow the user to toggle this behavior.

Describe alternatives you've considered
The user can define a custom HTMLTranslator that handles this, as demonstrated in the PR submitted to PyData Sphinx theme.

[bheberlein]

I'm happy to put in the work here, but would appreciate some guidance from more senior devs on what is the right way to do this. The PR linked above might provide a useful template, or not.

[12rambau]

After some more thoughts, we realized that the issue related to the anchor naming convention is only a problem when using the built-in ScrollSpy from Twitter Bootstrap. I think it should then be handled by us from the theme itself (either by using a custom SccrollSpy or use a bootstrap trick) and not from here.

@AA-Turner I let you review pydata/pydata-sphinx-theme#1435 and I think you can close this one.

[picnixz]

I've read the linked issue as well as the Bootstrap one. Since the latter agrees that dots are valid HTML5 ids, I think we can indeed close this issue.

On the other hand, we could change. by - but I am wondering whether we used the . to separate a name and a number. If this is the case, we may also need to change the design on our side to be a bit more robust, e.g., by having two dashes. Otherwise we can just change it normally.

[12rambau]

As the names are actual python names I don't think you can face a dots that separate a name and a number as you can't set a variable name as a number.

[picnixz]

Err, I don't understand the names. What do you mean by "python names"? they are just strings stored in the ids array of the node. What I meant is "how did we generate the ids in the first place?", namely, why were we adding some "."? I don't know if we use that for some index purpose for instance.

[12rambau]

ah sorry. These names are generated when documenting APIs via autodoc. The dots are just representing the path to the method in a python framework:

<my package>.<my module>.<my class>.<my method>

With of course all the alternative possible if you document a package variable, a module function, a submodule ... etc

[picnixz]

Ok, so we should keep those dots on our side because they are meaningful (actually I took the thing with name/number from the issues you linked and your examples with "id.1" etc).

[12rambau]

sure no problem. That's why I suggested to close the issue in the first place.

[picnixz]

Thank you. It's just that I wanted to be sure that we were on the same page. Now, I'll close the issue.