How do you use the right "Edit in Github" url for generated files?

[vnmabus]

For generated files, such as examples generated with sphinx-gallery or API reference pages generated with autosummary, the "Edit in Github" link generates a 404 error.

It is possible to redirect them to the original file somehow? In that case, how?

[drammock]

Duplicate of #1237 and already fixed by #1246. If you update to the dev version of the theme it should work; if not please open a new issue about it.

[vnmabus]

Are you sure this is a duplicate? I think that issue is a completely different case (a problem with the branch link, not a problem with autogenerated files).

The problem here is that the link does not work because the files that it points to do not exist on the repository (they have been generated during documentation build).

[drammock]

Ah, ok, sorry. I answered too hastily. I'll take a closer look at this on Monday.

[drammock]

ok, this may be a bit tricky. A couple examples:

Sphinx Gallery

actual link: https://github.com/mne-tools/mne-python/edit/main/auto_tutorials/intro/10_overview.rst
desired link: https://github.com/mne-tools/mne-python/edit/main/tutorials/intro/10_overview.py

(i.e., change auto_tutorials -> tutorials and change .rst -> .py). For that we could maybe check if sphinx_gallery_conf exists, and if so, get its examples_dirs and gallery_dirs entries and use those to get the correct path.

autodoc/autosummary

For the main autosummary page, the difference is in my case the doc folder, but this could be docs/source or similar depending on one's sphinx configuration:

• actual: https://github.com/mne-tools/mne-python/edit/main/python_reference.rst
• desired: https://github.com/mne-tools/mne-python/edit/main/doc/python_reference.rst

For generated pages, the file simply doesn't exist; closest thing would be https://github.com/mne-tools/mne-python/blob/main/mne/io/fiff/raw.py#L31-L426 (i.e., the [source] link for that class:

• actual: https://github.com/mne-tools/mne-python/edit/main/generated/mne.io.Raw.rst
• desired: n/a

I looked around to see if there's any way to detect during page building whether the current page is an autodoc/autosummary-generated one or not, but so far I haven't found a way to do it.

[12rambau]

For one of my poject, I gather files from the other github projects in the same documentation. To prevent this situation, I coded a small extention that take 1 argument (the path to the original file) and rewrite the "edit this page button" with Javascript.

"""Extention to dynamically change the value of the "edit this page btn"""

from typing import Dict, List

from docutils import nodes
from sphinx.application import Sphinx
from sphinx.util import logging
from sphinx.util.docutils import SphinxDirective, SphinxTranslator

logger = logging.getLogger(__name__)


class custom_edit_node(nodes.General, nodes.Element):
    """custom edit node"""

    pass


class CustomEdit(SphinxDirective):
    """Customize edit this page button
    Only compatblie with the current theme. The directive require the complete github link

    """

    has_content = False
    required_arguments = 1
    optional_arguments = 0
    final_argument_whitespace = False
    option_spec = {}

    def run(self) -> List[custom_edit_node]:

        return [custom_edit_node(link=self.arguments[0])]


def visit_custom_edit_node_html(
    translator: SphinxTranslator, node: custom_edit_node
) -> None:
    """Entry point of the html custom edit node"""

    html = """
    <script>
        document.addEventListener('DOMContentLoaded', function() {{
            var div = document.getElementsByClassName("tocsection editthispage")[0];
            var link = div.getElementsByTagName("a")[0];
            link.href = "{}";
        }});
    """

    translator.body.append(html.format(node["link"]))


def depart_custom_edit_node_html(
    translator: SphinxTranslator, node: custom_edit_node
) -> None:
    """exit point of the html custom edit node"""

    translator.body.append("</script>")


def visit_custom_edit_node_unsuported(
    translator: SphinxTranslator, node: custom_edit_node
) -> None:
    """Entry point of the ignored custom edit node."""
    logger.warning("CustomEdit: unsupported output format (node skipped)")
    raise nodes.SkipNode


def setup(app: Sphinx) -> Dict[str, bool]:
    app.add_node(
        custom_edit_node,
        html=(visit_custom_edit_node_html, depart_custom_edit_node_html),
        epub=(visit_custom_edit_node_unsuported, None),
        latex=(visit_custom_edit_node_unsuported, None),
        man=(visit_custom_edit_node_unsuported, None),
        texinfo=(visit_custom_edit_node_unsuported, None),
        text=(visit_custom_edit_node_unsuported, None),
    )
    app.add_directive("custom-edit", CustomEdit)

    return {
        "parallel_read_safe": True,
        "parallel_write_safe": True,
    }

[vnmabus]

It seems that this functionality does not currently exist. Should I make an issue from this discussion?

[drammock]

I already made it into an issue yesterday. I thought GitHub would automatically cross-link it but apparently not

[drammock]

#1269

[pllim]

FWIW in my case, the API doc is actually generated from docstring in Python code, so magic reroute logic might be too painful to write. I am okay with just option to disable "Edit on GitHub" links for those pages.