sphinx icon indicating copy to clipboard operation
sphinx copied to clipboard

Add toc entry autofunction

Open tdegeus opened this issue 4 months ago • 0 comments

Is your feature request related to a problem? Please describe.

Goal

I would like to add a toc entry to each .. autofunction: Suppose:

.. automodule:: foo.bar
   
   .. rubric:: Functions

   .. autosummary::
   
      myfunction
      otherfunction

   .. rubric:: Details
   
   .. autofunction:: myfunction
   .. autofunction:: otherfunction

Now I would like to add a TOC entry for each autofunction.

Background

To simplify the navigation, I would like to customise autodoc a bit, but still keep things automatic. I am using

.. currentmodule:: foo

.. autosummary::
    :toctree: generated

    bar

Together with a template _templates/autosummary/module.rst

.. This file is automatically generated

{{ name | escape | underline }}

.. automodule:: {{ fullname }}

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

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

   .. rubric:: {{ _('Details') }}

   {% if functions %}
   {% for item in functions %}
   .. autofunction:: {{ item }}
   {%- endfor %}
   {% endif %}

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

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

which generates `generated/foo.bar.rst

bar
===

.. automodule:: foo.bar
   
   .. rubric:: Functions

   .. autosummary::
   
      myfunction
      otherfunction

   .. rubric:: Details
   
   .. autofunction:: myfunction
   .. autofunction:: otherfunction

Now I would like to add a toc entry for each autofunction to help navigation.

Vaguely related to https://github.com/sphinx-doc/sphinx/issues/6316

Describe the solution you'd like For example an option

   .. autofunction:: myfunction
      :toc-entry: 2

(with the entry level)

Describe alternatives you've considered This seems to be all taken care of when one uses .. automodule:, so somewhere that should be an option to enable such behaviour.

tdegeus avatar Feb 26 '24 11:02 tdegeus