How to remove module and class prefix in TOC names?

[ShawnHymel]

I'm not sure if this is a Sphinx issue or a Furo issue, but I'll start here anyway. There are 2 things going on that I'd like help with:

1. All names in the TOC (left sidebar) are prepended with the package/module name. For example, edgeimpulse_api.api.admin_api module. Is there a way to remove the prefixes so that it just shows admin_api module? As it's underneath the edgeimpulse_api.api package drop-down menu, I figure this would be obvious to users, and it would make for a cleaner TOC in the sidebar.
2. All names in the page TOC (right sidebar) suffer from the same issue. For example, under AdminApi, the methods are listed as e.g. AdminApi.admin_add_disallowed_email_domain(). How do I get rid of all the AdminApi prefixes to just show the method as admin_add_disallowed_email_domain()?

I have tried setting add_module_names = False in conf.py, but that seems to just remove the module/class prefixes from the signature and does not affect anything in the TOC.

[dgw]

For 2, at least, I would check your toc_object_entries_show_parents setting in conf.py. With the default value ("domain"), in a Python project, I'm not seeing excessive prefixes in Furo's right sidebar.

(This might solve 1, too, but our docset is organized manually into pages, so auto-generated page titles based on the module name aren't used anywhere.)

[ShawnHymel]

Hi @dgw,

Thank you! I was looking for hours yesterday, and setting toc_object_entries_show_parents = "hide" did the trick to solve #2.

It did not help with #1. The closest I could find was to go through each .rst file and remove the package/module parents from the title. For example, in edgeimpulse_api.api.admin_api.rst, I changed

edgeimpulse\_api.api.auth\_api module
=====================================

to

auth\_api module
================

That helped make some of the longer titles much easier to read on the left sidebar and on the page itself (see screenshot).

My follow-up question: is there any way to change the title like this automatically (either in sphinx-apidoc or sphinx-build) without needing to manually edit every .rst file? My search has not turned up anything, and my backup plan is to create a pre-processing script that runs between sphinx-apidoc and sphinx-build that modifies the titles in all .rst files (not pretty, so I'm hoping to avoid this option).

[dgw]

sphinx-apidoc can generate conf.py (with --full), but doesn't read it, so I suppose it makes sense that options therein won't affect the command's behavior.

A lot of poking around the documentation and code for sphinx-apidoc has yielded no hints for modifying the names or titles it generates. It doesn't seem to have a ton of knobs you can tweak.

Granted, I've not used that part of Sphinx before, so I could be missing stuff. But it's definitely a sphinx-apidoc question at this point, and not a Furo one. At the very least, you might be better able to find the right IRC channel/discussion board/mailing list/etc. to ask the real question now: "How do I omit the package prefix from sphinx-apidoc page titles?" 😅

[ShawnHymel]

No worries, and that helps a lot, thank you! I found a Sphinx users Google group here, so I'll see if anyone there knows.

[nicrie]

I would like to do the same but face the same struggles as you @ShawnHymel . Did you eventually find a solution how to remove the module prefixes from the left hand side navigation bar (TOC)?

[nicrie]

Ok I've found your script you posted in the Google group. Somehow it still doesn't work for me. Although adding crawl_source_shorten_titles at the end of conf.py rewrites the .rst files, they are rewritten shortly after by another process so that I end up with the long titles again.

EDIT: solved it. the problem was that I use sphinx.ext.autosummary which overwrites all .rst files after conf.py has run. The solution was to use sphinx.connect()to jump into the build process somewhere after autosummary has created the rst files and before html are written.

[akaszynski]

For anyone still looking to solve this problem, here's a more condensed approach. Place this at the bottom of your conf.py:

from typing import Any
from sphinx.application import Sphinx


def shorten_autosummary_titles(app: Sphinx, *args: Any) -> None:
    """Remove module and class from the autosummary titles."""
    autosummary_dir = os.path.join(app.srcdir, "api", "_autosummary")
    if not os.path.exists(autosummary_dir):
        return

    for filename in os.listdir(autosummary_dir):
        if not filename.endswith(".rst"):
            continue

        path = os.path.join(autosummary_dir, filename)
        with open(path, "r") as f:
            lines = f.readlines()

        # skip if missing a title or if a module/class
        if not lines or lines[0].count(".") < 2:
            continue

        short = lines[0].strip().rsplit(".", 1)[-1]
        lines[0] = short + "\n"
        lines[1] = "=" * len(short) + "\n"
        with open(path, "w") as f:
            f.writelines(lines)


def setup(app: Sphinx) -> None:
    app.connect("env-before-read-docs", shorten_autosummary_titles)

[tyrrellgit]

Anyone coming at this from the future: using templates you're able to specify the header of each generated page. This header is then used as the toctree entry name.

If you use something like this one below for your module templates, it should shorted the names without any hassle.

{{ name | escape | underline}}


.. automodule:: {{ fullname }}

   {% block attributes %}
   {% if attributes %}
   .. rubric:: Module Attributes

   .. autosummary::
      :toctree:
   {% for item in attributes %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

   {% block functions %}
   {% if functions %}
   .. rubric:: {{ _('Functions') }}

   .. autosummary::
      :toctree:
   {% for item in functions %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

   {% block classes %}
   {% if classes %}
   .. rubric:: {{ _('Classes') }}

   .. autosummary::
      :toctree:
      :template: custom-class-template.rst
   {% for item in classes %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

   {% block exceptions %}
   {% if exceptions %}
   .. rubric:: {{ _('Exceptions') }}

   .. autosummary::
      :toctree:
   {% for item in exceptions %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

{% block modules %}
{% if modules %}
.. rubric:: Modules

.. autosummary::
   :toctree:

   :recursive:
{% for item in modules %}
   {{ item }}
{%- endfor %}
{% endif %}
{% endblock %}