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:
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:
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.
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).
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:
display: block
for dl.field-list
. I used all that qualification because otherwise it was overridden by the more specific CSS in the style itself.@media screen and (max-width:768px)
because this is what the RTD theme uses to decide when to hide the sidebar, but I found it was still overflowing in a window of moderate width, so I changed the threshold to 1024px
instead. Some might prefer to get rid of the conditional altogether.<dt>
and <dd>
(i.e. from a caption like "Returns:" to the content like "The return value is ..."). That's because <dt>
was getting an indentation of 1em
somehow, which was barely less than the indentation of the <dd>
. Setting that to 0 fixed the issue (and that's acceptable for my taste but some might have preferred to add indentation to the <dt>
instead. I left this out of the max-width
conditional because I even preferred the grid version to not be indented (there's already enough indentation in this theme).overflow-wrap: break-word
to fix the problem of very long identifier names.Here's the result on a narrow view port:
Here's the result on a wider view port (but still narrow enough that its matches the max-width:1024px
condition):