jupyter-sphinx-theme

jupyter-sphinx-theme copied to clipboard

(Opening this to keep track of the discussions on the subject.) Here is an opinionated take on the matter:

I think that we should not have a custom sphinx theme on RTD.

• The RTD team does a great job with their them that works on a large variety of browsers and mobile devices.
• They dedicate more bandwidth to this problem than the jupyter team will ever do. If one of us wants to work on this subject, it might be better to help them than trying to do our own thing.
• IMO, having a uniform style on all RTD-hosted docs is a nice feature of their web site and we would be better citizens if we adopted the main theme.
• The only case where we would need to customize things is when we need to add custom javascript such as inline widget rendering, but in this case I would be in favor of using their theme and only adding static resources for the inline widget renderer.

Now, for the Jupyter website, if we were to host our own version of the docs, we could do our own theme. But even then, the best solution is likely to use the most advanced theme out there that is the one of RTD plus some color changes.

cc @willingc @fperez @ellisonbg

Cross linking https://github.com/jupyter/jupyter/issues/176

I am fine with using whatever theme that the team believes is best.

I'm deferring to Fernando and Brian on this decision since Fernando had thoughts that shaped the existing jupyter.readthedocs.io site.

For the next two weeks, I am focusing on documentation content.

cc @JamiesHQ

I don't think it's especially important that we fit in with every other project on RTD, but I was a bit surprised when we made our own theme. If there isn't a good reason to make a separate one, I'm in favour of using something well made and spending time on other things.

I think the reasoning was to get a good experience, as well as allowing custom widget. I understand that having a custom theme for things related to a project might make a lot of sens, as it make often more obvious which project you are working on. Typically the conda-thing are green-is, and jinja documentation page is recognizable a mile away.

At the same time, having a coherent theme make context switching much easier, and it is extremely difficult to make a theme that works well in all corner cases.

@jdfreder and @willingc made an incredible job with what they have, unfortunately we hit the classical threshold in software engineering that once you've done 95% of the implementation, then there is 95% left.

So I think I would be in favor of spending cycle on RTD theme which have its share of issues we coudl help fix; potentially making the colors of its css (more) customizable if we want to have a sort of branding.

ok, I think that we are all on the same page. I am 👍 on @Carreau 's comment re: colors of the RTD theme.

quick technical detail I wanted to bring up: for the embedding of live widget, we need a custom theme to add additional static assets, but what I would prefer doing is use the bare RTD one plus and only add the required script tag with the static widget embedder from a cdn.

As you decide what approach to take with the documentation theme, here are a few more items that may be helpful:

• test document repo (from a couple of months ago) using the RTD standard theme: http://test-jupyter.readthedocs.io/en/rtd-theme/
• test document repo using the jupyter-sphinx theme in this repo http://test-jupyter.readthedocs.io/en/latest/
• the dark background RTD standard theme is more difficult to read than the lighter background used in the Jinja docs (alabaster theme)
• the more modern look of the light background was very positively received during the PyCon 2016 poster session PDF of poster PDF of second poster