New documentation theme

[dantownsend]

I've been looking at alternative themes for Sphinx.

Sphinx Material:

Pydata:

Furo:

And here's the original for reference, using the Read the Docs theme:

Furo seems to be the best maintained, but people I've asked prefer the look of Sphinx Material slightly more.

The reason I originally chose Sphinx was the ability to auto generate API docs. I'm a big fan of this approach, as it means that people browsing the code have useful docstrings to read. MKDocs didn't historically support this, but it now seems possible via a plugin.

Moving over to MKDocs would be quite a bit of work. I wouldn't even consider it, except that the Material for MKDocs theme is so good. One approach might be to convert all of the Piccolo projects to use Sphinx Material, and try moving one of the smaller projects (like Piccolo Admin or Targ) to use MKDocs.

Does anyone have any thoughts on this? Should we change, or just keep what we have?

[sinisaos]

@dantownsend I also like the current theme, but if you plan to change the theme, I like Furo the most. I tried on the Piccolo API documentation and just changed this in conf.py

html_theme = "furo"
pygments_style = "monokai"
pygments_dark_style = "monokai"

and result is very nice.

[dantownsend]

Thanks - I didn't realise you could change the Pygments theme.

[dantownsend]

I had a play around with Furo, and it does look good like you suggested. Every time I went back to the current theme though, it just seemed right for some reason. I've decided not to move from Sphinx. It's a minor pain sometimes, but it's so powerful.

So I'll keep with the current theme for now, and might move to Furo in the future.

I've been trying to tidy up the docs a bit, and adding a logo for each project.

There's now a logo for Piccolo admin:
https://github.com/piccolo-orm/piccolo_admin

And Targ:
https://github.com/piccolo-orm/targ

I was thinking something like this for Piccolo API.

[dantownsend]

@sinisaos I've been on a journey of discovery this week, learning as much as possible about documentation and Sphinx.

The culmination is this custom Piccolo theme:

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

It will be used for all Piccolo projects moving forward.

It's just version 0.1 so we can continue to improve it, but I'm excited about it.

What do you think?

[sinisaos]

@dantownsend Looks great 👍

[dantownsend]

Thanks!

[dantownsend]

The new theme is now live for Piccolo:

https://piccolo-orm.readthedocs.io/en/latest/index.html

Hopefully people like it!