Make it possible to put the entire site toctree in the left sidebar and populate the header with custom links

[choldgraf]

Context

Currently, the top-level sections of your documentation will become links in the header, and the left sidebar will only show the sub-sections for the active top-level section.

However, we've now seen many themes that instead want to define their own custom links in the top-level header, and then put the entire documentation structure in the left sidebar (similar to how a traditional Sphinx site works).

In this case, what sites usually do is add custom templating to the Sphinx Book Theme. Sites often use this in order to have the same theme across subsets of your documentation. for example:

• https://docs.2i2c.org
• https://docs.dask.org

Proposal

We could make it possible for people to achieve this effect without using a different theme by making two changes:

• Make it possible for the left sidebar to include the full site TOCtree instead of just the second-level items (e.g., via activating a template)
• Make it possible for the header links to only be external links (maybe with dropdowns as well)

[choldgraf]

cc @wtbarnes and @eteq who both mentioned this might be useful

[wtbarnes]

Also tagging @nabobalis as he has taken the lead on the refactor of the sunpy sphinx theme on top of the sphinx book theme.

[Rchatru]

Related to this issue, I have a doubt about this statement:

Currently, the top-level sections of your documentation will become links in the header

In my case the structure of my package is similar to the following:

.
└── my_package/
    ├── subpackage1/
    │   └── module1
    ├── subpackage2/
    │   ├── module2
    │   └── module3
    └── subpackage3/
        └── module4

And in header links, I only get a link to the top level element, in this case, "my_package", and I would like to have quick access from this bar, to the different subpackages. Would it be possible to modify the "depth", as can be done in toc, or manually add the links to these subpackages?

[dhapolapankaj]

Hello Guys,
I have a requirement here, I need to hide the right sticky panel and display the sub - heading (method name) permalink in left panel

Taking a cue from above example. I have a function1 as permalink in module1 below
Can we display the left sidebar in such a way that function1 permalink appears just below the module1?

.
└── my_package/
├── subpackage1/
│ └── module1
| └── function1
├── subpackage2/
│ ├── module2
│ └── module3
└── subpackage3/
└── module4