python-sphinxread-the-docs

How can I make ReadTheDocs theme for Sphinx lay out function parameters nicely for mobile?


The ReadTheDocs theme for Sphinx is a particularly nice and easy to read theme. It works very well on decent width displays. Here's an example:

Sphinx RTD example in wide view port

It also mostly also works very well on very narrow displays (as you'd get looking on mobile). However, at least one thing does poorly: the documentation for parts of a function signature overflow the right hand side. That's because the type of thing being documented ("Parameters:"/"Raises:"/"Returns:") forms a sort of column on the left which uses up a lot of the horizontal space. Here's the same example, showing this problem:

Sphinx RTD example in narrow view port

I'd prefer those captions to be on their own line like in the version below (which I manually constructed this with RST syntax), although ideally I'd like there to be less vertical spacing. This still overflows sometimes (with the really long type name) but it's a lot better. I'd even be happy if it was just like this unconditionally, even with wide displays.

Mock up of altered Sphinx RTD example in narrow view port

Is there a way to make the theme behave like the above image? Perhaps by overriding something in the theme's CSS?

Edit with some extra info: aioresult docs are the site in question. I've found that if I override the style of one of the relevant <dl> tags with display: block (in my browser's style inspector) then it fixes it, but there seem to be dozens of options for display and I don't know what the difference is - I'm not very familiar with CSS. Also, the indentation then looks far too small (not like my final image above). I also don't know how to target the custom CSS at only this type of definition list - it seems like <dl> is used for a lot of other things on the page (e.g. class name and everything underneath).


Solution

  • Here is some custom CSS I created to get the effect. I included it in my docs using the ReadTheDocs guide to How to add custom CSS.

    @media screen and (max-width:1024px) {
      html.writer-html5 .rst-content dl.field-list { display: block }
    }
    html.writer-html5 .rst-content dl.field-list > dt { padding-left: 0px }
    html.writer-html5 .rst-content { overflow-wrap: break-word }
    html.writer-html5 .rst-content dt.sig { display: block !important }
    

    Explanation:

    Here's the result on a narrow view port:

    Screenshot of fixed RTD theme

    Here's the result on a wider view port (but still narrow enough that its matches the max-width:1024px condition):

    Wider screenshot of fixed RTD theme