How do Sphinx configurations setup "breadcrumbs"?

Question

How do Sphinx configurations setup "breadcrumbs" in the header? I have a Sphinx project and all I see is the project name; if I jump down into subpages I get lost and I don't see the path to the current page.

Some examples in the wild:

https://docs.python.org/2.7/library/argparse.html

See top line: Documentation >> The Python Standard Library >> 15. Generic Operating System Services

http://docs.scipy.org/doc/numpy/reference/arrays.ndarray.html

See the rounded rectangles at the top

Source code for scipy appears to be here:

It looks like the Sphinx "basic" theme has this functionality built-in as the "relbar":

From https://github.com/sphinx-doc/sphinx/blob/master/sphinx/themes/basic/layout.html:

{%- macro relbar() %}
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>{{ _('Navigation') }}</h3>
      <ul>
        {%- for rellink in rellinks %}
        <li class="right" {% if loop.first %}style="margin-right: 10px"{% endif %}>
          <a href="{{ pathto(rellink[0]) }}" title="{{ rellink[1]|striptags|e }}"
             {{ accesskey(rellink[2]) }}>{{ rellink[3] }}</a>
          {%- if not loop.first %}{{ reldelim2 }}{% endif %}</li>
        {%- endfor %}
        {%- block rootrellink %}
        <li class="nav-item nav-item-0"><a href="{{ pathto(master_doc) }}">{{ shorttitle|e }}</a>{{ reldelim1 }}</li>
        {%- endblock %}
        {%- for parent in parents %}
          <li class="nav-item nav-item-{{ loop.index }}"><a href="{{ parent.link|e }}" {% if loop.last %}{{ accesskey("U") }}{% endif %}>{{ parent.title }}</a>{{ reldelim1 }}</li>
        {%- endfor %}
        {%- block relbaritems %} {% endblock %}
      </ul>
    </div>
{%- endmacro %}

see also http://www.sphinx-doc.org/en/stable/templating.html

But I can't figure out how to enable.

OK, I am really confused here. I got something to appear but not the way I wanted.

I have my index.rst for my project "MyDoc":

Top Level Page Title Is Here
============================

content goes here

.. toctree::
   :maxdepth: 2

   introduction
   (other files)

and then I have introduction.rst

Introduction
============

content goes here

.. toctree::
   :maxdepth: 2

   test1

and test1.rst

Test1
============

blah blah

For index.html it shows MyDoc in the relbar.
For introduction.html it shows MyDoc in the relbar. (I would have expected MyDoc >> Introduction)
For test1.html it shows MyDoc >> Introduction in the relbar. (I would have expected MyDoc >> Introduction >> Test1)

I guess what I am confused about is why it works this way.

It's open source, so you can go and *see* how they do it: https://github.com/scipy/scipy-sphinx-theme — jonrsharpe, Aug 05 '16 at 21:07
looks like it's `pydoctheme` for https://github.com/python/cpython/blob/master/Doc/conf.py — Jason S, Aug 05 '16 at 21:44
er... I guess I mean `parents` in the case of the "basic" theme. It will do the breadcrumbs, but somehow `parents` has to get set and I can't seem to do this. — Jason S, Aug 05 '16 at 22:36

score 2 · Answer 1 · answered Oct 09 '17 at 18:53

I'm not sure what question you are asking, as it seems like you have changed it at least once. From some of your later comments, however, it sounds like you expect the current document name to show as the final item in the breadcrumb links.

It so happens I was just trying to do exactly that myself. I ended up adding this to my layout.html:

{# Show the current document in the navigation bar. #}
{% block relbaritems %}
<li class="nav-item">{{ title|striptags|e }}</li>
{% endblock %}

...which seems to work well for me. I didn't make it a link, because a link to the current document seems unnecessary, but if you want that, it shouldn't be hard to figure out how to do it from looking at the base layout.html.

I didn't figure out how to hide it for the root document, however. If anyone knows how to do that, please follow up!

How do Sphinx configurations setup "breadcrumbs"?

1 Answers1