Ability to exclude certain paths from edit link rendering

[daneah]

For the packages we maintain internal to our org, we commit our handwritten doc files to version control, but we generate the API reference documentation (e.g. from docstrings) on-the-fly. As such, the edit links only work for the handwritten pages, and the edit links for the API pages result in a 404. It would be great to have a way not to render the edit links at all on those pages, to reduce confusion for those who stumble on a 404 and might assume the edit links are broken on all pages.

We render our API reference to a docs/references/ directory/subpath, so something like the following DX could certainly address our particular need (but I could imagine other approaches and rationales might direct this some other way):

html_theme_options = {
    ...,
    "source_edit_link_exclude_paths": {
        "docs/references/",
    },
}

Incidentally, also interested in how others manage generation and tracking of API reference documentation—particularly how you reduce the human error in forgetting to generate it, if you track it in version control.

[pradyunsg]

Are these API pages rendered in-memory? If so, can they have page-level metadata (similar to hide-toc) applied to them?

I think letting users hide this on a per-page basis might end up being a cleaner solution.

[daneah]

I think I used "on-the-fly" too loosely 😅 We don't generate them in memory, rather we generate them at site build time (with sphinx-apidoc). Even so, we probably could put some page-level metadata in at that juncture and I agree that a per-page basis would offer the most control!

[EFord36]

(not sure if this belongs as a reply, or a top-level 'answer' - but it's not an answer. I'm new to GitHub discussion so please tell me to move this if I shouldn't be piggybacking here!).

I have the same basic problem - I don't want to have an edit button on API doc, and my pages are similarly generated by sphinx.ext.autosummary (rather than sphinx-apidoc) - I have an api docs directory with a file like:

API Reference
=============

.. autosummary::
   :recursive:
   :toctree: _autosummary

   my_package_name

which generates a whole load of 'stub' files (which at the moment we're not actually editing further), which don't contain real content, only automodule and autosummary directives.

Being able to hide the button on a per-page basis would work well for me I think - I'm assuming I would then be able to modify the template that generates the stub files to then mark the pages for hiding the edit button on them.

[pradyunsg]

#620 filed for this.

[ailin-nemui]

we have added

:generated:

at the top of the documents. this is then available in the template files, e.g. edit-this-page.html in the meta[] dictionary

Then we can hide the edit button conditionally

[EFord36]

This sounds like it would work great for me - do you happen to have a snippet of of the relevant Jinja template(s) that you would be able to share?

No problem if not, I can figure it out myself, but just thought I'd ask in case you can easily share your solution (I'm a novice with jinja).

Are you basically importing furo_edit_button from Furo's components/edit-this-page.html template, and then call furo_edit_button only when generated isn't a key in meta? Roughly:

{% if link_available and not "generated" in meta %}
    { furo_edit_button(determine_page_edit_link()) }
{% endif %}

Thanks for your comment, it's already been a big help!

[ailin-nemui]

yes, more or less like that. we forked furo (need to catch up with the latest updates!), here is the commit we did at that time: e306461#diff-7ba89aa1dce062805604944e859899013b593c7f418f604a8d052023e5f69d1eR17 (but it also conflates some changes we did wrt. the link_available)

[EFord36]

Perfect, thanks for sharing!

[EFord36]

For future reference for anyone coming to this discussion trying to do the same thing, and to say thank you again to @ailin-nemui for guiding me in the right direction!

I finally got a chance to do this - it ended up being very simple once I knew what I was doing with Jinja a bit (never used it before seriously). I'm using the 'autosummary' Sphinx extension to generate my docs (but I imagine apidoc would be similar, I might try to find out and leave another comment if I get a change).

I already had templates_path = ["_templates"] in my conf.py, which is crucial, but then:

I added docs/_templates/autosummary/module.rst:

:generated:

{% include '!autosummary/module.rst' %}

and then added docs/_templates/components/edit-this-page.html:

{%- if not (meta is mapping and 'generated' in meta) -%}
    {% include "furo/components/edit-this-page.html" with context %}
{%- endif -%}