Re-purpose external_links to be an independent component called extra_links

[choldgraf]

We recently made it possible to put external links in the header by adding them directly in the toctree:

• FIX: display external links in toctree #1055

This makes "external link functionality" roughly duplicated between toctree-based external links, and external links that are provided in the conf.py.

It seems unnecessary to have the same functionality split between both, but I do think that we could use conf.py to define links outside of the toctree structure. This could then be its own independent component rather than something that is lumped in with the header navigation links component. This might let us expand its functionality a bit as well.

Proposal

I propose that we:

• Deprecate external_links in one or two releases, and use our current navbar-nav.html component just for toctree-generated links
• Add a dedicated header_extra_links component and configuration value, and use this to let people add links + link dropdowns that are outside of the toctree structure. This would behave similar to our current external-links configuration, with a couple differences:
  • Allow internal links as well, so if somebody pointed to a doc in the current page, it would resolve properly.
  • Allow dropdown menus to be defined (via a structure like {"kind": "dropdown", "items": [list-of-links]}.
• The "auto dropdown after N links" behavior would only apply to the toctree links, not the extra header links (because they can exist in their own dropdowns)

This would let us separate the functionality of toctree navigation links and other links a person wants to add, which could be useful for themes that want to have more control over the functionality of the header links. (for example, they could even remove the navbar-nav links entirely and define a fully custom set of links via extra-links lone.

Alternative implementation

If we wanted to keep things streamlined within a single "navigation links" approach, we could decide not to create a new HTML component, and instead add a configuration value for something like include_top_level_pages_in_navigation_links. If False, then the top pages wouldn't be in the navigation, and people could customize the remaining links via the extra_links configuration alone, without needing to utilize a different component.

References

Would also relate to

• Allow custom header links to include dropdowns #1016