pydata / pydata-sphinx-theme

A clean, three-column Sphinx theme with Bootstrap for the PyData community
https://pydata-sphinx-theme.readthedocs.io
BSD 3-Clause "New" or "Revised" License
613 stars 317 forks source link

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

Open choldgraf opened 2 years ago

choldgraf commented 2 years ago

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:

Proposal

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

choldgraf commented 2 years ago

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

wtbarnes commented 2 years ago

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 commented 1 year ago

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 commented 1 year ago

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