Allow configuring "On this page" content

[bgmeulem]

The furo theme is, as the docs state, biased to small projects. However, that didn't stop me from trying to adapting it to a larger project though. Hopefully this request isn't too niche because of that?

One adaptation to larger projects that I haven't been able to manage with Jinja2, Sphinx extensions, or custom templating is the content of the "On this page" section on the right hand side. It is super useful (especially for larger projects/pages) to quickly glance and jump to specific sections. I am experiencing two roadblocks I don't know how to tackle. My apologies if these aren't furo specific.

1. Long entries when using FQNs on a page

Furo uses the {{ toc }} command (see code below) to generate this page-specific toc, which takes the content directly from the page sections. These sections include directives like .. py:attribute: my_attribute etc. For large projects, the FQN is also large, and the "On this page" section becomes very cluttered. Each entry contains the parent module, class etc. For example, a class page like so:

.. py:class:: module.submodule.subsubmodule.class

   .. py:data:: attribute

would add an entry in the "On this page" toc with the name module.submodule.subsubmodule.class.attribute

It would be nice if we had the option to adapt the look of just the "On this page" section without having to adapt the directives.

Other things I have tried (and why I stepped away):

• adding a section heading on locations I want to anchor (They are very large and confuse the structure of the page more than they add, they also don't address the large names in the sidebar)
• Adapt the directives to .. py:obj: short_name instead of .. py:class: long_name for the parent page, be it a module or class (messes up internal reflinking and global index, names need to be FQNs for sphinx)
• Hidden section headings (don't know how to do this)
• Injecting code (don't know what to inject where)

2. Adding custom entries

On top of adapting the current entries, it would be nice to also add custom entries, especially in combination with custom templates. Currently, the only way I know of is manually adding sections. These render quite large in furo, especially compared to the class/module signature. In addition, it would be lovely to flag certain objects as "add me to the right hand sidebar" such as tables.

Many thanks in advance for any pointers. I believe I may have missed a handful of options, so do let me know if there are more things I can try.

Relevant snippet from page.html:

{% block right_sidebar %}
      {% if not furo_hide_toc %}
      <div class="toc-sticky toc-scroll">
        <div class="toc-title-container">
          <span class="toc-title">
            {{ _("On this page") }}
          </span>
        </div>
        <div class="toc-tree-container">
          <div class="toc-tree">
            {{ toc }}
          </div>
        </div>
      </div>
      {% endif %}
{% endblock right_sidebar %}

[nineteendo]

See this discussion for shorter toc names: #692

[bgmeulem]

Exactly what i needed, thanks!

I ended up adding entries to the sidebar by defining custom headings (using this answer: https://stackoverflow.com/questions/70990016/sphinx-force-subsection-before-section-in-a-document)