Add the option for a right sidebar

[choldgraf]

This is a suggestion for a new feature...I'd be happy to give a shot at implementing it if folks are interested.

I've found that, with a wide-enough screen, it's helpful to have a sidebar to the right with within-page links. Currently, the RTD theme includes in-page links within the TOC to the left.

In some of my projects, I've got a very small amount of CSS that will pop out the within-page links to the right of the page when the screen is wide-enough. It works something like this:

I'm wondering if this is something that would be useful as an addition to this theme...maybe something that could be activated w/ a particular configuration? My goal thus far has been to make this possible without modifying any of the HTML - it is a CSS-only modification, something like this:

@media screen and (min-width: 1270px)  {
    /* Pop out the in-page links to the right instead of the left */
    div.wy-side-scroll li.toctree-l1.current > ul {
        position: fixed;
        margin-left: 0px;
        overflow-y: auto;
        padding-left: 5px;
        border-left: 1px solid #767677;
        height: 95%;
        top: 70px;
        left: 1100px;
    }

    div.wy-side-scroll li.toctree-l1.current a {
        border-right: none;
    }

    div.wy-side-scroll li.toctree-l1.current ul {
        max-width: 400px;
    }

    div.wy-side-scroll li.toctree-l1.current ul, li.toctree-l1.current li, li.toctree-l1.current a {
        background-color: transparent !important;
    }

    /* All items should now be visible regardless of expandy state */
    div.wy-side-scroll li.toctree-l1.current ul {
      display: block !important;
    }

    /* hide the expandy buttons */
    div.wy-side-scroll li.toctree-l1.current span.toctree-expand {
        display: none !important;
    }

    /* Make the padding correct */
    div.wy-side-scroll li.toctree-l2 li.toctree-l3 > a {
      padding: .4045em 4.045em !important;
    }

    div.wy-side-scroll li.toctree-l4 > a {
      padding: .4045em 5.663em !important;
  }
}

There are some hacks in there, but I was impressed we could get such a big shift out of a relatively small amount of CSS.

Let me know if folks would be interested in this and I'm happy to discuss changes that would need to be made etc.

[agjohnson]

This is really neat @choldgraf! I fear that there is a lot baked into the theme currently around having a singular TOC menu though -- such as the javascript that selects the correct heading when linking to an achored heading, and the javascript to expand/hide nested navigation.

I do tend to like secondary navigation menus on docs, i wonder if there is a better way to achieve this sort of effect?

For instance:

• At the Sphinx doctree level, consume navigation headings above navigaition_depth and add this to a secondary element that we float to the right
• At the Sphinx doctree/build level, output a static file that we can use for parsing for a global navigation menu. Split this into multiple menus based on depth (we've talked about this for a while for in-doc search purposes)
• Add a directive for right-float contents:: directive (or contents with a float option)
• Repurpose sidebars over a certain screen size

I actually really like the sidebar option. Making use of the sidebar with actual content would help fill out the available space and use patterns already recommended in Sphinx. Not as nice as magic like the CSS option, but it's hard to wield magic well for thousands of projects at the same time.

[choldgraf]

heya - sorry for the slow response!

I agree with you it feels a bit hacky to use pure CSS to pop the sidebar to the right, and hacky things often break in unpredictable ways for people :-)

I'd be +1 on generating a right sidebar using in-page links with HTML and (optionally) inserting it into the page with its own dedicated CSS rules. I don't have a ton of cycles for figuring that out, but how can I be helpful in that process?

[agjohnson]

I don't have any solid guidance here yet. It might take some more exploring to figure out the best way to use the gutter and how we implement it to be the most useful.

I played very briefly with restyling sidebar on wide displays. Having sidebars in the gutter made for a much nicer display in the main content, but sidebars did feel a bit out of place in the gutter. I also tried to add a copy of the local TOC as a sidebar automatically, this was not consistent depending on how toctree was being used though.

I haven't gone as deep as pulling apart headings in the Sphinx doctree representation yet.

[choldgraf]

(just for my own knowledge, by "gutter" do you mean "the space to the right of the page"?)

[agjohnson]

Oh sorry, yeah the space to the right. :+1:

[arnons1]

I do tend to like secondary navigation menus on docs, i wonder if there is a better way to achieve this sort of effect?

For instance:

• At the Sphinx doctree level, consume navigation headings above navigaition_depth and add this to a secondary element that we float to the right
• At the Sphinx doctree/build level, output a static file that we can use for parsing for a global navigation menu. Split this into multiple menus based on depth (we've talked about this for a while for in-doc search purposes)
• Add a directive for right-float contents:: directive (or contents with a float option)
• Repurpose sidebars over a certain screen size

I think the right-float directive or similar would probably be the best idea for this

[jdillard]

I made an implementation using {{toc}} in PR #919 if anyone wants to try it out and give feedback:

[coding-to-music]

Right-hand TOC would be good, I would be interested in trying it out if you need some testing plz see the Help->About I am also interested in changing the color scheme and meta, I should add some issues etc. Thx - Tom https://pandemic-overview.readthedocs.io/en/latest/index.html

[zhaoweiguo]

It is a nice feature. For now, I have to use chrome Extension to do this.

[dylanh724]

Any update to this a few years later? All the other popular themes seem to support an optional 3rd column.