Upgrade Sphinx

[astrojuanlu]

Our blog doesn't need a lot of new Sphinx features, but upgrading would help us adopt some extensions and possibly have other small benefits. However, I tried upgrading to Sphinx 2.4 and the HTML changed, so our styles broke:

Therefore, this would require a bit of work.

[stsewd]

We use ablog

https://github.com/readthedocs/blog/blob/master/requirements.txt

I think we can check if ablog is compatible with the latest version of sphinx or if we need to update our custom templates https://github.com/readthedocs/blog/tree/master/_themes/rtd-blog

[astrojuanlu]

In this case, the issue seems to be in our local.css:

.postlist p.first {
    font-size: 24px;
}
div.section p {
    margin: .75rem .5rem;
    line-height: 1.6rem;
}

[astrojuanlu]

There are other styling issues before-and-after, like a different margin on the articles, and for some reason different translations. I wonder if @nienn would have some time to have a look at the CSS differences 😇

[nienn]

On a first glance over the screenshots it seems that Sphinx 2.4 is moving from the selector div.section to section. This should be changed across all instances of div.section in the CSS. In order to maintain combability with previous Sphinx versions the section selector should be added (not replaced) in each instance.

For example, this:

div.section p {
    margin: .75rem .5rem;
    line-height: 1.6rem;
}

Would become this:

div.section p,
section p {
    margin: .75rem .5rem;
    line-height: 1.6rem;
}

If they decided to move from div to section, which was not supported until IE9 and continued having some issues with some other browsers for a few years, then they probably updated other similar tags.

I still don't have my system ready to test multiple Sphinx versions but this is definitely something I could look over the next few days.

[stsewd]

@nienn here we just want our blog to be compatible with sphinx version we are going to use (2.4), so no need to worry about backwards compatibility.

[nienn]

@stsewd ok, I wasn't sure about that. Great to know! 😃

[agjohnson]

Actually, the easiest fix here might be to set html4_writer=True on the sphinx config. When upgrading to Sphinx 2, html5 writer becomes the default. This should preserve the class names. I would attempt that first.

Long term, I'd see us moving this content to Pelican perhaps, and so we'd have templates/styling completely different from what we have here now. I'm +1 on limping along here for now, but any obvious fixes are good to have in the meantime.

[astrojuanlu]

It worked, thanks @agjohnson ! Sending PR