ryan-roemer / sphinx-bootstrap-theme

Sphinx Bootstrap Theme
http://ryan-roemer.github.io/sphinx-bootstrap-theme/README.html
MIT License
586 stars 213 forks source link

Can navbar_links support menus and submenus #178

Open StevOmics opened 6 years ago

StevOmics commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

@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

https://github.com/ryan-roemer/sphinx-bootstrap-theme/blob/28c53695c63990d2bc20cf172776cb6f1ccce828/sphinx_bootstrap_theme/bootstrap/layout.html#L71-L82

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:

https://github.com/ryan-roemer/sphinx-bootstrap-theme/blob/28c53695c63990d2bc20cf172776cb6f1ccce828/sphinx_bootstrap_theme/bootstrap/layout.html#L28-L30

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 commented 6 years ago

Note also the duplicate feature request #156.

StevOmics commented 6 years ago

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: