Can navbar_links support menus and submenus

[StevOmics]

Is it possible to include menus within the navbar_links list (similar to 'page' and 'site' links)?

It seems like this would be a good format

'navbar_links':[
'help_menu':[
("this","here/there"),
("that","over/there"),
],

[iwelch82]

I think this would be a nice feature as well but i would propose that the Menu's use a toc instead of statically defined, must like the page and site links work today. By having the menu content dynamically generated a developer wouldn't need to change the conf.py file whenever the added a new page or section.

[svenevs]

@iwelch82 that sounds interesting, would you be willing to expand on how the mechanics of that play out? E.g. what is written in RST, does the user need to customize layout.html for this?

The reason I ask is something that's been on the (very) back burner I'd like to contribute is reworking how the menus are achieved. As far as I can tell the global toc is generated for every page, which means that larger projects get significantly slower build times. More than twice slower than RTD theme, for example.

I am worried that introducing another toc-like thing will make this worse, but in all honesty how all of the layout stuff works is still confusing to me.

@sdayers you may be able to override layout.html and use hard-coded options for now, but this will likely not be an easy process. See the sphinx templating docs for how to override. One thing the docs don't make super clear is how you actually get the override in there. In your conf.py there's likely the following commented out section:

# Add any paths that contain templates here, relative to this directory.
# templates_path = ['_templates']

Un-comment the templates_path variable. Now mkdir _templates and create _templates/layout.html. The name must be exact. Then Sphinx should use your new template.

In terms of what to change, I think you want to override the {% content %} meta-block

sphinx-bootstrap-theme/sphinx_bootstrap_theme/bootstrap/layout.html

Lines 71 to 82 in 28c5369

	{%- block content %}
	{{ navBar() }}
	<div class="container">
	<div class="row">
	{%- block sidebar1 %}{{ bsidebar() }}{% endblock %}
	<div class="{{ bs_span_prefix }}{{ bs_content_width }} content">
	{% block body %}{% endblock %}
	</div>
	{% block sidebar2 %} {# possible location for sidebar #} {% endblock %}
	</div>
	</div>
	{%- endblock %}

Then I think you basically want to copy-paste most of that code, only remove the call to navBar(). Test that first, it should result in no navbar. The navbar macro is defined above, and basically just includes the right version:

sphinx-bootstrap-theme/sphinx_bootstrap_theme/bootstrap/layout.html

Lines 28 to 30 in 28c5369

	{% macro navBar() %}
	{% include "navbar" + navbar_version + ".html" %}
	{% endmacro %}

So what you'll want to do now is work off of the navbar code (see the files in that same directory), and essentially copy-paste everything you want, and add these special links.

Having this as a bypass in the theme itself would definitely be nice (since that gets pretty bloody), but if you really really want it I think the above will get you close. Good luck!

[artob]

Note also the duplicate feature request #156.

[StevOmics]

Thanks for the comments! I've actually had a lot of success with this through templates. I'll post a demo. For now I'll summarize:

• What I did: Modified the menu items list in conf.py to include sub-lists (submenus) and updated the template to populate these (i.e., hard-coding the menus in the top level of the list).
• What I want to do: have the lists auto-populate based on the directory structure (i.e., find all directories in the source folder with content (index.rst files) and add these as menus, with cascading submenus as appropriate. I think this would make it downright easy to build a pretty decent looking site with minimal layout editing.