Custom theme isn't showing on rtd to test

[tony]

I am not sure if this is my config, the sphinx_rtd_theme package or readthedocs.org - but I can't get my branch of the theme - as a package or a submodule, to show on readthedocs.org.

https://github.com/tony/sphinx_rtd_theme/tree/sphinx-basic-updates (see doc/_rtd_theme)
https://github.com/tony/tmuxp/blob/rtd_theme_sphinx-basic-updates/doc/conf.py
https://readthedocs.org/builds/tmuxp/930992/

http://tmuxp.readthedocs.org/en/rtd_theme_sphinx-basic-updates/ - just shows normal rtd theme.

[chebee7i]

We ran into this with our project too. Our conclusion was that if it detects the theme name to be 'sphinx_rtd_theme', then it ignores whatever is in your repository and uses their version. If you change the name of the theme to something other than 'sphinx_rtd_theme', then it seems to do something...but its still wrong. Locally, everything looks great. For example, we have:

  <script type="text/javascript" src="_static/jquery.js"></script>
  <script type="text/javascript" src="_static/underscore.js"></script>
  <script type="text/javascript" src="_static/doctools.js"></script>
  <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML,http://dit.io/MathJax/local/dit.js"></script>

<link rel="stylesheet" href="_static/theme.css" type="text/css" />
<script type="text/javascript" src="_static/theme.js"></script>

But in the built docs, we have:

  <script type="text/javascript" src="https://media.readthedocs.org/javascript/jquery/jquery-2.0.3.min.js"></script>
  <script type="text/javascript" src="https://media.readthedocs.org/javascript/jquery/jquery-migrate-1.2.1.min.js"></script>
  <script type="text/javascript" src="https://media.readthedocs.org/javascript/underscore.js"></script>
  <script type="text/javascript" src="https://media.readthedocs.org/javascript/doctools.js"></script>
  <script type="text/javascript" src="https://media.readthedocs.org/javascript/readthedocs-doc-embed.js"></script>
  <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML,http://dit.io/MathJax/local/dit.js"></script>

<link rel="stylesheet" href="https://media.readthedocs.org/css/badge_only.css" type="text/css" /> 
<link rel="stylesheet" href="https://media.readthedocs.org/css/readthedocs-doc-embed.css" type="text/css" />

The reason we know it is actually incorporating our changes to the theme is that we can check _static/theme.css and see that it has our changes. However, as the above snippets show, _static/theme.css is not loaded by the RTD built docs at all.

[ericholscher]

This will be fixed tomorrow when we roll the theme out officially.

[ericholscher]

The later issue might not be. We have custom logic that we run when we're on RTD, which is when we don't insert the media files because we host them.

If you have customizations forking the theme is currently not the supported way to handle this. Please file bugs against the theme so we can improve it.

[tony]

The theme sphinx-rtd-theme open source and forkable. Pip allows targetting packages by forks/branches.

Someone could, in theory, have customization for a fork of sphinx-rtd-theme that probably wouldn't be useful to the upstream project. In practice, if it was useful, they'd be PR it anyway to save them the load of maintaining a parallel fork + get the glorious pr ego boost.

I may look into this when I finish a few other things. If I start at something I'll mention back here.

[sehmaschine]

so we're still not able to use custom themes? or am I doing something wrong?

http://django-grappelli.readthedocs.org/en/stable-2.5.x/

I added a folder _themes (with a renamed fork of sphinx_rtd_theme) which is part of my repo, the build with RTD works fine but the theme doesn't seem to be loaded.

[chebee7i]

Am I correct in inferring that you are interested in supplying your own layout.html? If so, yes, I think that is still an issue. See #152. The page.html hack works well for some customizations.

[sehmaschine]

no, I wanna use my own styles. there shouldn´t be a hack involved in using a custom theme, right?

[ericholscher]

We have custom logic that we run when we're on RTD, which is when we don't insert the media files because we host them.

If you have customizations forking the theme is currently not the supported way to handle this. Please file bugs against the theme so we can improve it.

[sehmaschine]

It's not bugs: IMHO the current theme can be improved in terms of readability/usability, but I already opened an issue and @snide decided to not take action (which is fine). Now I want to add the updates myself … you're telling me I'm stuck with the theme provided by RTD? No way around this?

[ericholscher]

Add an option to configure the media handling, and add it back to the default theme, and use it in your fork?

[sehmaschine]

good idea — but how can I remove the RTD static files? Is it the line for cssfile in css_files?

[sehmaschine]

it's working, see http://django-grappelli.readthedocs.org/en/stable-2.5.x/
I just needed to remove the css_files and {% if not READTHEDOCS %}.

If I find the time, I might add the media handling option … but I can live with this solution for now. thanks four your support.

[ericholscher]

Closing this, since if it is still an issue, its a problem with the theme and not RTD.