Add injection of HTML to a signal #13

ericholscher · 2016-01-19T00:23:56Z

This is because there's no way to consistently add things into <head> via Sphinx. The doctree node that is used internally only represents the body of the document, and theme's are responsible for wrapping it with proper HTML. There is no standard for block naming and other issues within the <head> -- so we are left with inserting HTML into the bottom of the body element as the most consistent way to override Sphinx's HTML content...

Fixes #12

agjohnson · 2016-01-20T17:18:43Z

readthedocs_ext/readthedocs.py

+def finalize_media(app):
+    """
+    Point media files at our media server.
+    """


We're not using pep257 on the extension yet, though we should. This single line comment should be on one line

Would be easy to enable on this repo at least, since it's tiny. I can work on that.

Not a huge priority, I opened #14 to deal with it later. I'm sure there will be some cleanup required as well

agjohnson · 2016-01-20T17:23:23Z

Just noted some updates to docstrings to match pep257. We should implement our tox config here eventually as well. I'll open an issue on that.

This all seems reasonable, without testing it directly. 👍

ericholscher · 2016-02-27T16:22:30Z

Either way, if the search stuff is ready to go, we can merge it, and then make it gets migrated into this PR. We could merge this one first also, and update the search PR, either way.

agjohnson · 2016-02-27T19:50:53Z

I have the search stuff pointing to the 0.6-alpha branch of the sphinx-ext, so order shouldn't matter. Search changes should be ready to go, probably with one last review pass. I can get the two PRs up on moving those changes here, we can get these PRs into 0.6-alpha once merged to master, and then make the change to readthedocs.org to drop layout.html?

ericholscher · 2016-02-27T20:07:55Z

Sounds good. I'm around today if we want to get the search & extension stuff deployed so we can catch issues with it over the weekend.

agjohnson · 2016-02-27T20:16:23Z

readthedocs_ext/_templates/readthedocs-insert.html.tmpl

+{% if page_source_suffix %} 		
+<!-- Add page-specific source suffix, which must exist in the page data, not global -->
+<script type="text/javascript">
+READTHEDOCS_DATA['source_suffix'] = {{ page_source_suffix }}


This should be quoted, and should be changed in the data file template as well. Does this exist here to ensure the change for projects built with a readthedocs-data.js but could be out of date?

I added this change to the template in #17 either way.

Edit: sorry, just realized only new projects will get this either way, as it's the template include. It doesn't seem we should implement this change here at all, no?

The data file is per project, not per-page.

Roger, this just needs to be quoted then. I'll reflect the change in #17

agjohnson · 2016-02-27T20:27:10Z

readthedocs_ext/readthedocs.py

+            return content
+
+        app.builder.templates.render = rtd_render
+        HAS_MONKEYPATCH = True


The global state tracking here seems unneeded, what about:

if app.builder.templates.render != rtd_render: app.builder.templates.render = rtd_render

Or is there a reason to avoid setting this again here?

Because we need to capture the old render function to be able to wrap it. We can't create the new render function without having a reference to the old one, so we have to know whether app.builder.templates.render is the original or our version, which I believe requires a global, no?

Yeah, this is capturing old_render, which will be in scope in the rtd_render closure. If testing for if render == rtd_render is enough here, then the HAS_MONKEYPATCH should be superfluous

How do you test for rtd_render without defining it though? And to define it you have to have imported render already, and wrapped it?

Sorry, by global, I was only referring to the global HAS_MONKEYPATCH, the rest looks fine, assuming we can add a test for app.builder.templates.render != rtd_render without causing problems.

Right, but we can't wrap it multiple times, because we're altering the output. I don't know a better way to do this? redefining rtd_render makes it a new function, so there's no way to know if it's the one that we set or not without global state, unless I'm missing something?

Oh, I see what you mean, on second pass, rtd_render is redefined. I think storing this information on the object we're monkey patching is more useful. This could be either with a pattern similar to mocking:

class WrappedCallable(object): def __init__(self, fn): print('WRAPPING') self.fn = fn def __call__(self, *args, **kwargs): print('PRE') self.fn(*args, **kwargs) print('POST') def foo(): print 'FOO' old_foo = foo if not isinstance(foo, WrappedCallable): foo = WrappedCallable(foo) if not isinstance(foo, WrappedCallable): foo = WrappedCallable(foo) foo()

or simply storing this on the function object:

app.builder.templates.render._is_patched = True

or something

Yea, I went ahead and threw it on the app, since I don't trust the templates object not to be re-initialized.

Put what on app? I was saying that instead of tracking HAS_MONKEYPATCH in our module, we should be tracking that state on the object we're passing. The first approach above tracks the function we've patched already, though we can also do this with the second approach -- that is, something like:

if not getattr(app.builder.templates.render, '_wrapped_call'): old_render = app.builder.templates.render def rtd_render(...): ... context = old_render(...) ... rtd_render._wrapped_call = old_render app.builder.templates.render = rtd_render

This is just an example, its untested.

This gives users the ability to reclaim app.builder.templates.render._wrapped_call, if something is completely broken with our patching. It also provides a truthier test if the object is actually patched.

gotcha, that makes sense.

agjohnson · 2016-02-27T20:32:39Z

Also, this gets rid of my changes that were just moved in for in-doc search in #16

agjohnson · 2016-02-27T22:49:28Z

Just thinking of this now. The extra head template should output all of this into <head>, not <body>.

First, <link rel="" /> is invalid in <body>, given the HTML spec[1]:

If the rel attribute is used, the element is restricted to the head element. When used with the itemprop attribute, the element can be used both in the head element and in the body of the page, subject to the constraints of the microdata model.

But, also, I believe we need much of this javascript loaded earlier.

1: https://html.spec.whatwg.org/multipage/semantics.html#the-link-element

agjohnson · 2016-02-28T00:27:25Z

Opened readthedocs/readthedocs.org#2021 to address some potential issues stemmed from javascript load order.

Add injection of HTML to a signal

Add injection of HTML to a signal

3dfe962

ericholscher mentioned this pull request Jan 19, 2016

Remove overriding of Sphinx templates readthedocs/readthedocs.org#1946

Merged

ericholscher added 3 commits January 18, 2016 16:34

Move media insertion to injection

3f39361

Move CSS to injection too

cc36a4f

Clean up extension

e508942

agjohnson reviewed Jan 20, 2016
View reviewed changes

Finish cleaning up refactor

9c297a1

agjohnson mentioned this pull request Jan 20, 2016

Implement tox config with standard tests and linting #14

Closed

ericholscher added 9 commits January 20, 2016 10:14

Merge branch 'master' into remove-layout-html

0a1e1c3

Fix linting and single line comments

2d6813b

One more

da097ad

Fix linting once more :)

3e70a18

Add basic integration test

98b5a34

Merge branch 'remove-layout-html' into add-tests

3f5067b

Test media insertion

3223293

Kill makefile

5bcbef2

Add a couple more tests

1164c29

agjohnson mentioned this pull request Feb 19, 2016

Build process missing layout.html readthedocs/readthedocs.org#152

Closed

agjohnson added this to the v0.6 milestone Feb 24, 2016

Monkey patch template renderer to include our HTML

d1c0389

ericholscher force-pushed the remove-layout-html branch from 9a7dafd to d1c0389 Compare February 27, 2016 00:35

ericholscher added 6 commits February 26, 2016 16:40

Properly check for truthyness

a466558

Small bit

b724d28

Properly set source_suffix on page

756a514

Fix setup.py

413779f

Only monkey patch our builder

8e0719f

Gate builder type properly

feeed3a

agjohnson reviewed Feb 27, 2016
View reviewed changes

agjohnson mentioned this pull request Feb 27, 2016

Move search doc page context additions #17

Merged

agjohnson reviewed Feb 27, 2016
View reviewed changes

ericholscher added 12 commits February 27, 2016 12:40

Fix review feedback

802bd7e

Merge remote-tracking branch 'origin/master' into remove-layout-html

5063324

Consistent quoting

978de13

Output the theme_css

6013ed5

Do case insensitive find

a7c0ba1

Fix LaTeX errors

586c034

Fix logic

b2a3264

Account for dirhtml builder too

1252856

Include page in local data, not global as well

eec0ea5

Fix conditional around page_source_suffix

6e5d52b

Fix monkeypatch

453ed9e

Fix lint

3c08387

ericholscher and others added 4 commits February 27, 2016 14:51

Put content in head not body

4241c88

Move RTD content creation into the closure

d2f4c52

Small additions to monkey patch closure

0e63ae0

Move rtd javascript to script_files addition from head addition

4762869

agjohnson added a commit that referenced this pull request Feb 28, 2016

Merge pull request #13 from rtfd/remove-layout-html

a3734ad

Add injection of HTML to a signal

agjohnson merged commit a3734ad into master Feb 28, 2016

agjohnson deleted the remove-layout-html branch February 28, 2016 00:40

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add injection of HTML to a signal #13

Add injection of HTML to a signal #13

ericholscher commented Jan 19, 2016

agjohnson Jan 20, 2016

ericholscher Jan 20, 2016

agjohnson Jan 20, 2016

agjohnson commented Jan 20, 2016

ericholscher commented Feb 27, 2016

agjohnson commented Feb 27, 2016

ericholscher commented Feb 27, 2016

agjohnson Feb 27, 2016

ericholscher Feb 27, 2016

agjohnson Feb 27, 2016

agjohnson Feb 27, 2016

ericholscher Feb 27, 2016

agjohnson Feb 27, 2016

ericholscher Feb 27, 2016

agjohnson Feb 27, 2016

ericholscher Feb 27, 2016

agjohnson Feb 27, 2016

ericholscher Feb 27, 2016

agjohnson Feb 27, 2016

ericholscher Feb 27, 2016

agjohnson commented Feb 27, 2016

agjohnson commented Feb 27, 2016

agjohnson commented Feb 28, 2016

Add injection of HTML to a signal #13

Add injection of HTML to a signal #13

Conversation

ericholscher commented Jan 19, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

agjohnson commented Jan 20, 2016

ericholscher commented Feb 27, 2016

agjohnson commented Feb 27, 2016

ericholscher commented Feb 27, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

agjohnson commented Feb 27, 2016

agjohnson commented Feb 27, 2016

agjohnson commented Feb 28, 2016