Replace the doc theme with the pydoctheme

[faho]

Released under the Python Software Foundation License (i.e. a GPL-compatible BSD-style permissive license), this one
doesn't look awful (no green top bar, huzzah!).

Lightly forked it to remove the donation footer (we don't take any)
and to change the python references to fish references.

The image is just our favicon, which is a stylized "f" and therefore
not fantastic (are we facebook?), but it's the best I found, and the
thing before had no images at all.

Fixes #6500
(as far as I'm concerned)

---

I'd much rather take this as a stop-gap, even if we end up replacing it with a fully custom theme eventually, but I'm not going to do that as I have the artistic talent of a drunk sloth.

[faho]

(sorry, forgot to push the first commit of this to master, it's entirely separate)

[faho]

Oh, screenshots would probably be helpful.

Before:

After:

[IlanCosman]

Hmm, I know we were having trouble settling on a logo for 3.0 😂 , but it would be cool to have a unified design language/color scheme for fish. I rather like the gradient watery blue + white from fishshell.com. Perhaps something like that could be done for the docs, and even the logo (if that ever gets solved).

EDIT: I think that the proposed doc theme looks a bit too corporate perhaps. As you said elsewhere fabian, fish is the scrappy underdog. While I agree the old doc theme with the bright green bar is a bit silly, it feels like it has a bit more personality.

[faho]

Hmm, I know we were having trouble settling on a logo for 3.0 joy , but it would be cool to have a unified design language/color scheme for fish

I'm going to leave picking colors to the non-colorblind. The only thing I'll do is complain if I can't read something.

EDIT: I think that the proposed doc theme looks a bit too corporate perhaps

The proposed theme is clear and not ugly. That makes it better than the current one.

This does not have to be the final theme we end up with, it especially doesn't have to be perfect in terms of every single color accent - those are just values in a config file.

If a good designer ended up making a bespoke theme that would be super cool!

But: This is available now, we can just click the merge button and have it. If no designer ever ends up making a bespoke theme I'd rather have this than what is before.

Of course if you went on for example https://sphinx-themes.org/ and picked out a theme with a suitable license that you like better I'm happy to take a look at it and try to adapt it,

[IlanCosman]

After glancing at every theme on https://sphinx-themes.org/, i'm of the opinion that the cloud_sptheme would be the best option. It looks nice and is reminiscent of fishshell.com, and could likely be tailored to fit even more snuggly.

Here's the preview I viewed: https://sphinx-themes.org/html/cloud_sptheme/cloud/index.html

It is most currently being hosted/developed at https://foss.heptapod.net/doc-utils/cloud_sptheme.

EDIT: Perhaps their own first-party preview would be better: https://cloud-sptheme.readthedocs.io/en/latest/cloud_theme.html

[faho]

Okay, looking at that theme it's... not great.

It looks nice, but the implementation leaves me unimpressed. It's > 4000 lines of code, among other things it scrolls the sidebar via javascript, and I've not gotten the subheaders to expand - so it would just give "Syntax overview", but not e.g. "Parameter expansion" and such. That alone makes the ToC basically useless.

We could fix that, but my guess is fixing it would be a more involved process than the rather simpler python theme.

[faho]

Messing some more with the python theme:

(note: this is the exact gradient from fishshell.com, but because the site is longer the gradient is softer)

[IlanCosman]

Wow, if you'd led with that out of the gate I wouldn't have had any complaints 😂 That looks great.

[ridiculousfish]

Agreed, latest screenshot looks really nice to me!

[faho]

Okay, I'm going to merge this as it stands for now since it's apparently an acceptable starting point.

I've played with some other things, like adding the colored background to headers again:

but I think that might be overemphasizing the headers and I don't like how the "fish_prompt" line isn't separated enough from the "Synopsis" one here.

Anyway, that's enhancements for later.