ABlog support for furo theme

[damian-krawczyk]

Description

Hi, I would like to use ABlog with furo theme, but I'm encountering an error:

Here simple example with alabaster theme (works with ablog): https://sphinx-ablog-alabaster.readthedocs.io/en/latest/ https://github.com/damian-krawczyk/sphinx-ablog-alabaster conf.py : html_theme = 'alabaster'

Here simple example with pydata_sphinx_theme (works with ablog) https://sphinx-ablog-pydata-sphinx-theme.readthedocs.io/en/latest/ https://github.com/damian-krawczyk/sphinx-ablog-pydata_sphinx_theme conf.py : html_theme = 'pydata_sphinx_theme'

Here simple example with furo (doesn't work with ablog, see error) https://sphinx-ablog-furo.readthedocs.io/en/latest/ https://github.com/damian-krawczyk/sphinx-ablog-furo conf.py : html_theme = 'furo'

The only difference in listed repositories is mentioned config.

I've already raised issue for furo but before I get back to them I would like to get feedback from you to make sure that this is not something to be fixed on your side?

[nabobalis]

Ah I see its from the URL. I missed that.

Honestly, I have no real idea where to start with that error.

[sudopluto]

commented on the furo issue, but it looks like that theme doesn't allow using layout.html. luckily, only two places it's referenced in ablog: https://github.com/sunpy/ablog/search?q=layout.html

[jmones]

I don't know much about the Sphinx template system (I just started tried to setup a blog with furo theme).

Tried to extend page.html and redirect.html from furo's page.html instead of layout.html seemed to work for both listings and redirections. It also seemed to keep working with alabaster theme.

Tried that with this patch and @damian-krawczyk 's PoC https://github.com/damian-krawczyk/sphinx-ablog-furo patch_to_make_ablog_work_with_furo.diff.txt

I don't know if this will break other themes or end users installations.

I don't propose a PR directly because I don't understand either why Sphinx Doc proposed different layout.html and page.html templates and how each one is supposed to be used (if someone could post an explanation, that would be interesting).

And I have no idea either of which option is the best for this issue:

• make ablog use page.html (this patch)
• make juro allow users and extensions to override layout.html
• setting an option in ablog to allow users select which base template it's going to be overriden (https://github.com/wpilibsuite/sphinxext-rediraffe seems to do something like that with their rediraffe_template configuration option)
• ...

[jmones]

The previous patch was wrong... Didn't work when I tried to use it in a more complex example. This seems to be better: patch_to_make_ablog_work_with_furo_take_2.diff.txt

[damian-krawczyk]

At furo's end Issue moved from Issues to Discussions by @pradyunsg https://github.com/pradyunsg/furo/discussions/262

[damian-krawczyk]

@nabobalis Can you check furo's comment?

https://github.com/pradyunsg/furo/discussions/262#discussioncomment-1656466

[nabobalis]

@nabobalis Can you check furo's comment?

pradyunsg/furo#262 (reply in thread)

I see, if someone wants to fix this assumptions, I am happy to accept the patch.

[stonecharioteer]

Is anyone working on this? @nabobalis I can try to contribute.

[nabobalis]

Is anyone working on this? @nabobalis I can try to contribute.

I am not aware that anyone is working on it. If you want to try to help, please go ahead.

[pradyunsg]

I've proposed an approach for solving this problem, at scale, in #125 that I think will be more sustainable for all the maintainers involved.

[SilverRainZ]

Doesn't this issue seem to be fixed? I can reproduce it on sphinx 6.2.1 + ablog 0.11.6 + furo 2024.

• Demo: http://silverrainz.me/ablog-demo/
• Source: https://github.com/SilverRainZ/ablog-demo

[SilverRainZ]

I found that there are still {%- extends "!layout.html" %} in ablog/redirect.html:

https://github.com/sunpy/ablog/blob/de37cf013846ceccae0e9e478f4ed6e1bd2dd0d3/src/ablog/templates/ablog/redirect.html#L1

[nabobalis]

I should add a test build to check compatibility with furo.

[SilverRainZ]

@nabobalis Any plan to fix it? I have no idea how to do that :'(

[nabobalis]

I will try but I won't promise an ETA.

[Jaharmi]

I still see the “layout.html” problem as well.

ERROR: This page was generated by inheriting from "layout.html".

Furo (the documentation theme that this site is generated with) does not support this, and has generated this page. If you are the author of this documentation, please look into why this page was generated using the "layout.html" template and fix the root cause.

Debugging information, if you need to report this error somewhere:
Sphinx: 7.2.6
Furo: 2024.01.29

pagename: index

This is with Ablog 0.11.6. The moment I set the template to Furo when Ablog is enabled, I get this problem. If I change either the theme or disable the Ablog extension, the problem goes away.

[damian-krawczyk]

Hi @errbufferoverfl Looks like you have been able to solve it out here https://www.errbufferoverfl.me

Could you share some thoughts on how to make it work?

[hspaans]

@damian-krawczyk the furo repository was forked and modified to make it work, see https://github.com/pradyunsg/furo/compare/main...errbufferoverfl:furo:main?diff=unified&w= for the diff.

Looking at a lot of other themes all are using layout.html instead of base.html that furo is using to work around this requirement in Sphinx Theme documentation:

When extending a template in the base theme with the same name, use the theme name as an explicit directory: {% extends "basic/layout.html" %}. From a user templates_path template, you can still use the “exclamation mark” syntax as described in the templating document.

To be honest I wonder if it will not be easier and quicker to fork furo and make it follow the file layout other themes are using or figure out a way to make ablog work with furo that would be a one-off as it looks right now.