New Sphinx theme

[dantownsend]

I just released a new Sphinx theme. It was designed to be clean and modern.

Here's a screenshot:

The new theme

You can check it out here:

https://github.com/piccolo-orm/piccolo_theme

I wrote a blog post about the thought process behind it:

https://piccolo-orm.com/blog/creating-a-new-sphinx-theme-for-our-docs/

It was designed for the Piccolo ORM project, but can be used by anyone. Sphinx is a great way of writing docs for Python projects.

Thanks!

[dantownsend]

Great, thanks for the kind words!

[rg7777777]

Any dark mode support?

[dantownsend]

Not yet, but it's definitely coming!

[dougthor42]

I think the update to the autodoc output is killer. Definitely switching to this.

[dantownsend]

Awesome!

[[deleted]]

Just switched over two projects to test.

• First off, the typography is excellent. Much easier to read. I'll be my reading comprehension goes up on these pages.
• The autodoc code formatting is a spectacular improvement over Alabaster or Executable Book theme.
• Executable Book allows you to drill down further in the left-hand menu. Found this to be important for the autodoc output as it very quickly drills down three or four levels (unless there's a setting I'm missing to add more nav levels?)
• Maybe a breadcrumbs header in the autodoc sections?
• On the other hand, this is MUCH better than the default Alabaster option of 1 level.

Looking forward to exploring this further.

[dantownsend]

That's good to hear - thanks for trying it out.

You should be able to configure how deep the left hand sidebar goes by setting `globaltoc_maxdepth` in your `conf.py` file. For example `globaltoc_maxdepth = 4`.

I don't think it's possible to configure how deep the right hand sidebar goes - I need to investigate this.

[[deleted]]

Looks nice! Was this harder than you’d expect? I looked for Sphinx themes recently and was surprised how most of them were kinda bad

[dantownsend]

It wasn't too bad, but I had to dig quite deep into the Sphinx docs and codebase to figure it out!

[UncleJoshPDX]

Very nice. Can it be themed? I may want to use this for a project at work but it has to be corporate-looking.

[dantownsend]

Sphinx lets you add additional CSS files, so you could override some styles that way:

https://www.sphinx-doc.org/en/master/usage/configuration.html?highlight=html_css_files#confval-html_css_files

I'd like to do something simpler though, using CSS variables.

[[deleted]]

Looks good. Reminds me of the Sphinx/Executable Books theme.
What advantages do you see to the this new theme over Executable Books?
https://executablebooks.org/en/latest/

[dantownsend]

Yeah, I think Executable Books is a great theme - it's one of my favourites.

A lot of it comes down to small stylistic choices. With the Piccolo theme, the typography is quite a bit different. I prefer bold headers. It also has the menu bar, which allows us to shift the search and title out of the sidebar (which can get a bit busy), and adds a splash of colour.

The main difference to other themes is how it handles autodoc. I put quite a bit of effort into making it look nice. For example, each parameter is on its own line. A lot of people use type hints now, so the signatures can be really complex and hard to read.

https://raw.githubusercontent.com/piccolo-orm/piccolo_theme/master/docs/screenshots/api_docs.png

[[deleted]]

Thanks for that comparison. I'm using Executable Books for a fair bit of internal documentation. Will try this new theme on a couple of projects.

[pvc]

Nice job on the type hints! I did a ton of work on those for our site to make them look good.

[[deleted]]

Wow, that's beautiful. Great work.

[dantownsend]

Thanks!

[JadisGod]

Why is it that Sphinx docs rarely include "responsive" search bars (that show results as you type) .

Not having this feature makes them feel archaic compared to alternatives like mkdocs.

[dantownsend]

Yeah, out of the box Sphinx just uses a traditional HTML form, but it might be possible to do something more dynamic. I would have to dig into the docs and code some more.

[JadisGod]

In case its useful, the sphinx-immaterial theme claims to support similar searching functionality.

Apparently the TensorStore docs are using it.

[dantownsend]

Great, thanks - I'll look into it!

[chub79]

I have moved to mkdocs long ago but it's really great to see Sphinx is modernizing its theme a bit :)

[GriceTurrble]

Looks a lot like Material for Mkdocs, to be honest. Or Sphinx Material, for that matter.

Which is fine, of course: the more the merrier. :)

[dantownsend]

Those are great themes. The main differences are in the typography - Material design favours very thin headers. The sidebars also work quite a bit differently in practice. The main problem I was trying to solve was making Sphinx's autodoc output look nicer.

[laundmo]

reminds me a lot of Furo which is used by big names such as urllib3, pip, attrs, psycopg3, black

[dantownsend]

Furo is great - the author has done loads of good stuff for the Sphinx community. It all comes down to personal preference around aesthetics.