Fix documentation issues

[marcinz]

Need to generate heading anchors and the link must be absolute to work in Sphinx.

[marcinz]

Unfortunately, to create a link to the file, one must hardcode the version of the tree. That creates an issue where this must be updated periodically. @bryevdv, is there a better way to do that?

[bryevdv]

is there a better way to do that?

Not that I am aware of, out of the box. For Bokeh we created a custom sphinx role to link to the right branch automatically:

https://github.com/bokeh/bokeh/blob/74b1f1a227dd1aa4735caa13199e79986b7e67f5/src/bokeh/sphinxext/bokeh_roles.py#L176-L203

    app = inliner.document.settings.env.app

    tag = app.env.config["version"]
    if "-" in tag:
        tag = "main"

    url = f"{BOKEH_GH}/tree/{tag}/{text}"
    options = options or {}
    set_classes(options)
    node = nodes.reference(rawtext, text, refuri=url, **options)
    return [node], []

I could add a similar directive to our Sphinx setup if that's desired. We just need to be able to get the version from somewhere in the config.

[bryevdv]

Though, apologies, I just realized this was in the README, not the sphinx docs. The custom role will really only help for versioning repo links that are in ReST sources. For the README, we could point a link to HEAD, and that is supposed to always go to the current default branch, not sure if that is more or less desirable. If we want the README to be correct "per-branch" then I think we will just be stuck updating the link in the README every time we rev a new branch.

[manopapad]

For the README, we could point a link to HEAD, and that is supposed to always go to the current default branch.

I think we can just do that for now. The plan is to move away from copying the .md files to the sphinx tree anyway, and at that point we can remove this explicit link from README.md.

[bryevdv]

one suggestion