Build process missing layout.html

[miohtama]

Plone's developer documentation is using a custom layout.html template with Sphinx 1.1.2. This adds some documentation specific links to the source code. For some reason these changes are not picked up

• Footer block has some injected HTML
• Head block has some injected <script> Javascript

How "native" Sphinx build HTML looks like:

http://opensourcehacker.com/wp-content/uploads/docs/

How readthedocs.org HTML looks like:

http://collective-docs.readthedocs.org/en/latest/index.html

I am still new to readthedocs.org - is there something special that needs to be done for custom layout.html or is it supported at all? (XSS injections and stuff)

[ericholscher]

Yea, this is a known issue since RTD ships its own layout.html for
customizing things on our end. I am calling the super() in our template,
but I believe won't render another layout.html once it finds ours.

If you know a way to work around this is Sphinx, let me know, otherwise I
don't really know a good way to handle this.

On Mon, Jan 2, 2012 at 6:07 AM, Mikko Ohtamaa <
reply@reply.github.com

wrote:

Plone's developer documentation is using a custom layout.html template
with Sphinx 1.1.2. This adds some documentation specific links to the
source code. For some reason these changes are not picked up

• Footer block has some injected HTML
• Head block has some injected <script> Javascript

How "native" Sphinx build HTML looks like:

http://opensourcehacker.com/wp-content/uploads/docs/

How readthedocs.org HTML looks like:

http://collective-docs.readthedocs.org/en/latest/index.html

I am still new to readthedocs.org - is there something special that needs
to be done for custom layout.html or is it supported at all? (XSS
injections and stuff)

---

Reply to this email directly or view it on GitHub:
#152

Eric Holscher
Engineer at Urban Airship in Portland, Or
http://ericholscher.com

[miohtama]

Ok.

For me it's enough to

1. Inject head HTML

2. Inject some hidden HTML somewhere (I think this can be done with left hand slots)

As I don't know Sphinx template system well yet, I'll accept tips how to do 1)

[miohtama]

I am now doing an attempt to use page.html overrides instead of layout.html. Is there something I need to do to force full rebuild on readthedocs.org?

[miohtama]

Ok. It works!

http://collective-docs.readthedocs.org/en/latest/index.html

[miohtama]

FYI the custom HTML isn't applied to search pages etc. now, but at least main documentation pages receive it when overriding page.html

[ericholscher]

Wow! That is a really great idea, and might be something that is worth
encorporating into RTD proper. I've long wanted to make RTD have a nice
editing interface, but this at least seems like a good middle ground.

Is the code on your end pretty customizable? I'm guessing it just needs to
know the github repo on the end to link to, and it can fill it out with the
proper file on build?

On Sun, Jan 8, 2012 at 4:58 AM, Mikko Ohtamaa <
reply@reply.github.com

wrote:

FYI the custom HTML isn't applied to search pages etc. now, but at least
main documentation pages receive it when overriding page.html

---

Reply to this email directly or view it on GitHub:
#152 (comment)

Eric Holscher
Engineer at Urban Airship in Portland, Or
http://ericholscher.com

[miohtama]

Here is a long'ish blog post how it was done http://opensourcehacker.com/2012/01/08/readthedocs-org-github-edit-backlink-and-short-history-of-plone-documentation/ and here the details https://github.com/collective/collective.developermanual/blob/master/source/_templates/page.html

[miohtama]

Also note that Sphinx lacks "full filename with extension" template variable which would be needed for a generic solution

[ericholscher]

Yea, we have the information in some form within RTD, so we could inject it
into the Sphinx conf.py and then pull it back out in the template, like we
do with some other variables.

On Sun, Jan 8, 2012 at 12:24 PM, Mikko Ohtamaa <
reply@reply.github.com

wrote:

Also note that Sphinx lacks "full filename with extension" template
variable which would be needed for a generic solution

---

Reply to this email directly or view it on GitHub:
#152 (comment)

Eric Holscher
Engineer at Urban Airship in Portland, Or
http://ericholscher.com

[miohtama]

Nah, how about fixing it in Sphinx itself? :)

[wojdyr]

layout.html from RTD extends "!layout.html" -- the "!" is handled in sphinx.jinja2glue.BuiltinTemplateLoader.get_source().
! makes Sphinx skip template path, so only sphinx templates are searched.
It is possible to make a workaround using template_bridge in conf.py so both RTD's and project's layouts are used, although it's rather ugly hack:

(the first try didn't work, so my change is in two commits)
wojdyr/fityk@1e8a668
wojdyr/fityk@4206cda
http://readthedocs.org/builds/fityk/60656/

If you want to change it in RTD code for all projects, I think the simplest way would be to use another magic prefix in RTD's layout.html, e.g. ?layout.html, and then add to get_source():

        if template.startswith('?'):                                            
            loaders = loaders[1:]                            
            template = template[1:]

(not tested)

[ericholscher]

Interesting. I will have to try and figure this out at a general level, as it seems useful.

[msabramo]

I just ran into this too last night. I was trying to add a "Fork me on GitHub" ribbon to my readthedocs page (http://readthedocs.org/docs/pycon-2012-notes/). Perhaps there is a better way to do it, but my attempt involved using a custom layout.html which worked locally with Sphinx but readthedocs didn't pick it up.

Should this issue be reopened? Being able to use a custom layout.html would be a nice feature.

It might also be interesting to have a feature where you can check a box in your project's settings and automatically get a "Fork me on GitHub" ribbon. If folks agree with the concept, I can take a stab at a patch to add it to readthedocs.

[msabramo]

@miohtama That's cool what you did! I wonder if you considered having your widget link directly to the "edit" URL on GitHub -- e.g.: https://github.com/collective/collective.developermanual/edit/master/source/index.rst (basically just change "blob" to "edit"). That removes one step for the user and then you can simplify your instructions a bit.

[wojdyr]

I've opened an issue in Sphinx tracker
https://bitbucket.org/birkenfeld/sphinx/issue/903/support-for-two-layouthtml-templates
to find out what sphinx developers think about it.

Anyway, I think it's trivial to fix it in RTD, add three lines to sphinx.jinja2glue.BuiltinTemplateLoader.get_source() and change ! to something else in RTD layout.html. (that's what I thought when I looked into it 2 months ago, but I may be completely wrong).

[ericholscher]

Reopened, and I will go ahead and look into implementing this on RTD in the next few days. If someone works up a pull request, I might get to it sooner. Once it's on there, I'd also love to have some help testing and documenting this, though if I read it correctly, it should "Just Work"

[miohtama]

@msabramo Do you know how Github handles following direct edit situations in your suggested solution

• You are repo owner (should not be problem)
• You are not logged in
• You are not repo owner, but you have a personal work
• You are not repo owner and do not yet have a personal work

[msabramo]

@miohtama Sorry, no I don't. They seem fairly easy to test though.

[msabramo]

I'm curious if there was any progress on this?

[ericholscher]

Ran into another problem with this today. Not sure a great way to fix it still, sadly :/

I'm wondering if using page.html instead of layout.html for the RTD specific stuff might help, or some other way of getting out of the way easier.

[ericholscher]

The extension work and new theme should hopefully make it so we can stop overriding the layout.html. There is still one bit of information we need in each page (the page's name), so it may not be possible, but we're getting closer.

[gregmuellegger]

@ericholscher What's the current status of this?

[ericholscher]

It's still an issue, where we use it for our customizations.

On Tue, Jul 21, 2015 at 4:43 AM, Gregor Müllegger notifications@github.com
wrote:

@ericholscher https://github.com/ericholscher What's the current status
of this?

—
Reply to this email directly or view it on GitHub
#152 (comment)
.

Eric Holscher
Maker of the internet residing in Portland, Oregon
http://ericholscher.com

[kennethreitz]

This has been driving me crazy all month. Relieved to find this page and find our I'm not doing anything wrong.

An easy solution is give a project the option to disable RTD's html meddling for a given project.

[agjohnson]

We are working to remove some of this with our sphinx extension, namely #1946 and readthedocs/readthedocs-sphinx-ext#13

[kennethreitz]

I almost moved my docs off RTD, but was able to workaround this limitation by adding my custom css/js as a sidebar on all pages.

[agjohnson]

@kennethreitz if you just need to add custom javascript/css, another method is to include files via the Sphinx application API in your conf.py:

def setup(app):
    app.add_javascript('foo.js')
    app.add_stylesheet('foo.css')

More:
http://www.sphinx-doc.org/en/stable/extdev/appapi.html#sphinx.application.Sphinx.add_javascript

Soon we shouldn't need a layout.html override however.

[kennethreitz]

@agjohnson ah, fantastic. Thanks! :)

[agjohnson]

Good news everyone!

We have just merged and deployed changes to RTD and our Sphinx extension that move RTD specific overrides into our Sphinx extension, without the need to override layout.html anymore. We're instead monkey patching the template rendering, injected our necessary changes there.

This might cause some different breakage, but we will deal with those changes as they come up. Feel free to open any new issues that might stem from this tomfoolery.

[macrocosme]

This may not be exactly the fix requested, but by overriding the sidebartitle block from rtd layout.html, I managed to change the link to something other than the master_doc.

So, in my own _layout/layout.html, I override it with the following:

{% block sidebartitle %}

      {% if logo and theme_logo_only %}
        <!-- a href="{{ pathto(master_doc) }}" -->
        <a href="http://www.home.org/">
      {% else %}
        <a href="http://www.home.org/" class="icon icon-home"> {{ project }}
      {% endif %}

      {% if logo %}
        {# Not strictly valid HTML, but it's the only way to display/scale it properly, without weird scripting or heaps of work #}
        <img src="{{ pathto('_static/' + logo, 1) }}" class="logo" />
      {% endif %}
      </a>

      {% if theme_display_version %}
        {%- set nav_version = version %}
        {% if READTHEDOCS and current_version %}
          {%- set nav_version = current_version %}
        {% endif %}
        {% if nav_version %}
          <div class="version">
            {{ nav_version }}
          </div>
        {% endif %}
      {% endif %}

      {% include "searchbox.html" %}

{% endblock %}