Skip to content

Add toc entry autofunction #12015

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tdegeus opened this issue Feb 26, 2024 · 0 comments
Open

Add toc entry autofunction #12015

tdegeus opened this issue Feb 26, 2024 · 0 comments

Comments

@tdegeus
Copy link

tdegeus commented Feb 26, 2024

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 #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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant