Template rework

[nabobalis]

Trying to fix the templates and tidy them up.

Fixes https://github.com/sunpy/ablog/issues/143 Fixes https://github.com/sunpy/ablog/issues/125 Fixes https://github.com/sunpy/ablog/issues/108

It still doesn't work with the furo theme tho. I am unsure where to go from here.

In addition:

• Moved to a disqus controlled by the sunpy team.
• removed the automate deploy change since its old and uses travis.
• removed fonts and css from the docs and used a cdn link instead

TODO

• [x] Update release page for 0.11

[pradyunsg]

FWIW, one template that we do not want to move is page.html. That's the template that affects the actual Sphinx rendering, since Sphinx renders for (almost) every HTML page and we want to override that for alabaster (the default theme).

[pradyunsg]

So... I did some preliminary testing, starting with ablog start from the main branch, building with that branch, then switching to this branch and making changes until things build, and finally switching to Furo to see how things build. Notes below.

---

Everything with main worked correctly -- ablog start followed by sphinx-build. :)

note 1: The ablog start's conf.py template should get the same treatment as https://github.com/sphinx-doc/sphinx/issues/10056, as well as a cleanup of the stuff it's got that's redundant/useless today (alabaster doesn't need to be imported, os and sys are unused, generated code isn't black-ready etc). We may also want to switch to using sphinx-quickstart's templating logic directly, instead of doing .format on a hard-coded string in a Python file -- I'll file a PR for this sometime soon.

---

On the first build with the new ablog, users will get the following error:

loading pickled environment... failed
failed: No such config value: inject_templates_after_theme

Extension error (ablog):
Handler <function builder_inited at 0x104675c10> for event 'builder-inited' threw an exception (exception: Found the path from `ablog.get_html_templates_path()` in the `templates_path` variable from `conf.py`. Doing so interferes with Ablog's ability to stay compatible with Sphinx themes that support it out of the box. Please remove `get_html_templates_path` from `templates_path` in your `conf.py` to resolve this.)

I really like this error message! It provides clear context on what went wrong, why that's a problem and what the user can do. We don't have control over the specific presentation out of Sphinx and that would be my only complaint about this.

However, once I resolved that by following the instructions, you get the following error:

Theme error:
An error happened in rendering the page about.
Reason: TemplateNotFound('postcard.html')

This is coming out of the html_sidebars declaration, and is a very opaque error message. We should improve this.

note 2: We should write a "migrating from {old} ablog to {new} ablog", as a blog post. I'd be happy to write this. :) note 3: I think it's sensible to add back the "old" files, with the following content:

{{ warning("foo.html is an old template path, that is no longer used by ablog. Please use ablog/foo.html instead.") }}

This would mean that users see a warning from Sphinx, that provides guidance, instead of the opaque error above.

---

Changing the theme to Furo hits https://github.com/pradyunsg/furo/blob/main/src/furo/theme/furo/layout.html. After I added the following to Furo's theme.conf (and removed alabaster-specific files from html_sidebars), things rendered with Furo's page.html template! 🎉

[ablog]
inject_templates_after_theme = true

This means that it is definitely possible now, to add first-class support for ABlog in Furo and other themes! Right now, quite a few things don't render correctly with Furo and the default templates from ABlog, but that's expected and something for future me to deal with. Right now, I'm very excited! :)

[nabobalis]

note 1: The ablog start's conf.py template should get the same treatment as sphinx-doc/sphinx#10056, as well as a cleanup of the stuff it's got that's redundant/useless today (alabaster doesn't need to be imported, os and sys are unused, generated code isn't black-ready etc). We may also want to switch to using sphinx-quickstart's templating logic directly, instead of doing .format on a hard-coded string in a Python file -- I'll file a PR for this sometime soon.

Yes that part of ablog is pretty old now, it would be great to improve this.

note 2: We should write a "migrating from {old} ablog to {new} ablog", as a blog post. I'd be happy to write this. :)

That would be incredible! It is something that would need to exist before a release. I have created a 0.10 branch and plan add multiple versions to RTD so people can check the old version for a while.

note 3: I think it's sensible to add back the "old" files, with the following content:

{{ warning("foo.html is an old template path, that is no longer used by ablog. Please use ablog/foo.html instead.") }}

I will do that in this PR as well but I use the updated html files from this PR.

Changing the theme to Furo hits pradyunsg/furo@main/src/furo/theme/furo/layout.html. After I added the following to Furo's theme.conf (and removed alabaster-specific files from html_sidebars), things rendered with Furo's page.html template! 🎉

[ablog]
inject_templates_after_theme = true

This means that it is definitely possible now, to add first-class support for ABlog in Furo and other themes! Right now, quite a few things don't render correctly with Furo and the default templates from ABlog, but that's expected and something for future me to deal with. Right now, I'm very excited! :)

That is brilliant, I want to thank you for your help again on this PR.

[pradyunsg]

@nabobalis Anything I can do to help move this forward?

[nabobalis]

@nabobalis Anything I can do to help move this forward?

I am not sure, I forgot about this and got the wrong import which is why the CI is broken.

But I think in theory its complete. So maybe just a glance over the Python changes would be ideal to make sure its all sane.

[nabobalis]

Other than the need to fix the wrong setup for the dev build. I think everything is in place.

[nabobalis]

LGTM, based on a desk skim.

Thanks again. I will branch off main to keep a 0.10 branch around for a bit and then merge this.

[choldgraf]

🎉

[bowentan]

Hi, I still got the error for layout.html when using the latest ablog with furo theme. Is the problem unresolved? Or do I need additional works on configurations?

[nabobalis]

Hi, I still got the error for layout.html when using the latest ablog with furo theme. Is the problem unresolved? Or do I need additional works on configurations?

Hello, this patch never made it to a release version at the moment.

My plan was to ship this in 0.11 but I got distracted and have not done a release of that.

[bowentan]

Hello, this patch never made it to a release version at the moment.

My plan was to ship this in 0.11 but I got distracted and have not done a release of that.

Oh i see.. Thanks!

[Jaharmi]

I am also seeing this on a new site / test setup I'm working on. I had ablog 0.10.30 installed and made sure it was updated to 0.10.33. It looks like there is no 0.11 release yet.

[nabobalis]

Yes unfortunately that is the case. Real life has got in my way recently and that will not change for me until Christmas.

[nabobalis]

Sorry it has taken me this long but I released ablog 0.11.0rc1.

I did not want to release such a large change without at least a brief RC period.

So if those who wanted to try this out for me, that would be great.

I plan to test some of the projects I maintain that use ablog as well but its a very limited test.

[choldgraf]

Nice - sounds good I will give it a shot and open issues